Updating the package deprecation policy and processes
by Andreas Enge and Sharlatan Hellseher —
sponsored by Simon Tournier
Accepted
Timeline
04 March
drafting06 March
discussion20 April
deliberation04 May
accepted
Summary
A deprecation policy has been added to the Guix manual in August 2024: https://guix.gnu.org/manual/1.5.0/en/guix.html#Deprecation-Policy. After more than a year of experience with the policy, this GCD aims at formalising and improving the processes that have organically developed around package removal, package renaming and moving packages between modules, with the goal of striking a balance between keeping the distribution up to date and building on one hand, and minimising disruption in particular for downstream channel administrators and users on the other hand.
Motivation
The current deprecation policy very succinctly describes reasons for deprecating packages (due to removal, name changes or updates), fixes some delays and describes how to use the macros attached to deprecation. It does not describe a precise workflow, nor does it treat the question how deprecations should be communicated besides macros in the code. Even if it did, our move to Codeberg would require to adapt our processes to the new environment.
Package deprecation, and in particular package removal, inherently causes
tensions due to conflicting valid goals.
On one hand, it is desirable to have a package collection that completely
builds at all points in time. Users get a correct picture of which packages
are available for installation, and it can be tested easily whether a
proposed pull request breaks any packages by simply trying to build the
dependencies without having to compare with a list of packages that are
already broken before the new commit.
If pushed to the extreme, this could be solved by removing any broken
package immediately.
On the other hand, vanishing or renamed packages disturb users who have
installed them previously, break packages in channels relying on packages
from the main Guix channel, and at worst a removed variable that is still
referenced in a channel breaks guix pull.
If pushed to the extreme, this could be solved by keeping broken packages
and obsolete variables indefinitely.
Package removal following the current policy requires a one month notification period; for broken packages that are in principle maintained upstream, it imposes additionally that the package has not been building for at least two months, a piece of information that is not readily available from our build farms. In any case, this may lead to a three months waiting period, and with one removal often conditioned by the previous removal of another package, this makes the goal of a completely building distribution close to impossible. Practice has also shown that the length of the waiting period is not a crucial factor: People generally react to the notification of a pending deprecation either in the days that follow (by proposing a pull request solving the problem or approving or contradicting the proposed course of action), or right after a removal when they missed the notification. One of the goals of this GCD is thus to define a short and sufficiently simple deprecation process, while clarifying the notification mechanism.
Additionally, depending on the reason for deprecation, the impacts on users and packagers are not the same, and different balances can be struck. Consequentially, this GCD aims at proposing processes that are adapted to the different situations.
Detailed Design
Removal of not building packages
From a user perspective, a package that does not build is effectively
equivalent to a package that does not exist: It cannot be installed or
updated, and neither can packages that depend on the broken one, whether
they come from Guix proper or another channel. So such a package
immediately becomes a removal candidate. However, removing the variable may
break compilation of channels that import it, and thus break guix pull.
And of course, some time is required for informing about the breakage and
enabling packagers to propose a fix.
A pull request removing such a package should be filed on Codeberg
with the deprecation tag. Additional justification for the
(non-)importance, obsolescence etc. of the package is welcome, but not
required. Deprecation pull requests can easily be
consulted
by interested parties.
Such a pull request may be merged at least three weeks later if there is
no opposition to the removal or if nobody has volunteered to repair the
affected packages.
Removal of building packages
There are various reasons while packages may become removal candidates although they still build: For instance we may have a newer version of the same package in Guix, maintenance has stopped upstream, or the package is not adequately maintained in Guix.
Removal candidates that are building leaf packages
It makes sense to distinguish two cases.
Leaf packages that by their nature are used mainly as inputs to other packages (for instance libraries, but also older compiler versions) require build farm capacity and maintenance work for little to no gain; they may be removed following the above process, assuming that there is no opposition to the removal or that consensus for the removal has been reached.
Leaf packages that are typically installed into user profiles (for instance applications, but also packages used in a service) are not per se a problem and may still be useful. They should not be removed unless there are particularly good reasons, such as security implications, in which case they may be removed following the above process.
Removal candidates that are building packages with dependent packages
Removing building packages on which other packages depend causes more disruption than removing leaf packages, since at the same time all dependent packages need to be removed. This may still be desirable for overarching reasons. For instance, we want to remove older versions of packages for which newer versions are already packaged, remove packages that are unmaintained or have reached end of life upstream, or that suffer from security vulnerabilities.
In this case, the removal candidate may be removed together with all packages depending on it following the above procedure. If the removal candidate falls into the realm of a team, this team must be notified, and consensus shall be sought about the removal in particular with this team. Reasonable efforts shall be made beforehand to update or otherwise preserve dependent packages.
Package renamings
As stipulated in the current deprecation policy, the name field of packages
may be changed at any time, provided that the old name is made available
through the statement (define-deprecated-package OLD-PACKAGE NEW-PACKAGE).
The old name must remain available for six months, and to ease its removal
after this period, the deprecation date should be stated in a comment next
to it.
Moving packages between modules
As the Guix package collection expands, it may become desirable to
reorganise the packages into different modules: For instance, an
initial science module grows over time, and turns out to be more
manageable when split into physics, chemistry and so on.
At a first glance, this resembles package renamings, since the
concatenation of a module and a package name, such as in
(gnu packages chemistry) molequeue, can be considered as the fully
qualified package name. However, deprecated-package cannot be used,
since it may lead to circular dependencies between modules and thus break
compilation; also deprecating a package by one with the same name leads to
nonsensical warning messages suggesting that a package is superseded by
itself. Instead, the variable itself should be marked as deprecated
in the old location for at least six months, for instance by adding
```
(define-deprecated/public-alias NAME
(@ (gnu packages NEW-MODULE) NAME))
in `gnu/packages/OLD-MODULE.scm`.
## Package additions
Care shall be taken when adding packages that these do not already
fulfill the criteria to become a removal candidate immediately after
addition.
## Cost of Reverting
The GCD does not completely overturn the current deprecation policy;
partially it only codifies and amends existing practices that have
developed over time when implementing the policy. It fixes steps to
follow and modifies delays to be respected. If these or any other part
of the GCD turn out to have side effects that were not adequately
considered, the procedure can easily be amended to be applied
going forward.
# Drawbacks and Open Issues
The GCD aims to strike a balance between making changes easy for packagers
to quickly and constantly improve the package collection, and minimising
disruption to users and channel maintainers. The deliberation period will
show whether this has been reached.