Hello all, as discussed during the Guix days and on Codeberg already, we would like to submit a GCD to update the deprecation policy and refine the processes. The full proposal is attached.
With the GCD process not yet amended to take the Codeberg migration into account, it is not quite clear how to navigate the discussion. GCD 001 speaks about the issue number, so it would be natural to discuss on Codeberg at the pull request: https://codeberg.org/guix/guix-consensus-documents/pulls/12 but I will also monitor the mailing list for replies in this thread. Simon Tournier agreed to sponsor this GCD, thanks a lot for his implication! Andreas
title: Updating the package deprecation policy and processes id: 006 status: submitted discussion: https://codeberg.org/guix/guix-consensus-documents/pulls/12 authors: Andreas Enge and Sharlatan Hellseher sponsors: Simon Tournier date: <date when a decision is taken> draft-date: 2026-03-04 discussion-date: 2026-03-06 deliberation-date: <date when the deliberation starts> SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later --- # 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] (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 deprecation, 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. # 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, an 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 unreachable. 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 removal candidate should be made public by filing an issue on Codeberg with the `deprecation` tag. Additional justification for the (non-)importance, obsolescence etc. of the package is welcome, but not required. Deprecation issues can easily be [consulted](https://codeberg.org/guix/guix/issues?q=&type=all&labels=445131) by channel administrators. Additionally, the team `deprecation` will be created on Codeberg to which interested parties can subscribe (for instance, one participant per interested downstream channel), and the issue body should reference the team so that their members get notified of the issue. The team is not a Guix team in the sense that their members obtain voting rights for GCDs or particular rights on the git repository; this makes it possible to accept all subscribers regardless of their contributions (or lack thereof) to Guix. A pull request regrouping removals for issues that are open for at least one week without opposition to the removal, or for which consensus for removal has been reached, can be created. The pull request must remain open for at least one week before being merged. The idea is that it should be picked up by some QA process that reports breakage beyond the removal (although most removal commits are simple, this has happened in the past). This entails a reasonable amount of additional work compared to the current practice of immediately pushing removal commits to the main branch. The commits need to be created anyway, and regrouping several removals in one pull request limits the extra work. Should consensus on a removal be lost (for instance because repair work on a package has started in the meantime), the corresponding commit can simply be dropped when merging. So altogether, this leaves (at least) two weeks between filing a removal issue and the actual removal, which leaves enough time to channel administrators to react accordingly. ## Removal of outdated libraries which are leaves The balance is different for packages than can still be built, but that are outdated in some sense (because they are abandoned upstream or for which we have another, newer version in Guix). It makes sense to distinguish between packages that serve mainly as inputs to other packages (for lack of a better word called *libraries* in the following, although their exact nature may depend on the programming language) and packages that users frequently install into their profiles (called *applications* in the following). The distinction is not always obvious; for the sake of this GCD, for instance, we treat compilers as libraries. Removing an outdated, but still building library that is a leaf in the dependency tree has almost as little impact as removing a broken package. On the other hand, keeping the library also has little impact beyond wasting build farm capacity. We follow the same removal process as above, but the initial removal notification is prolonged from one week to three weeks. ## Removal of outdated applications An outdated application that builds is not a priori a problem, and it may still be useful. So it should not be removed unless this has security implications. The situation is different, however, if it depends on an outdated library: It is not desirable to keep an arbitrary number of old versions of a library that require build farm capacity for a small number of applications that are not updated to newer library versions. In particular, this concerns libraries with rapidly changing APIs such as fmt and boost, but in the long run we will also wish to get rid of Python 2, Qt 5 or GTK+ 2, for instance. In this case, the outdated library may be removed together with all other libraries and applications depending on it. Since application removal can be particularly disruptive, the removal procedure above is applied with an initial notification period prolonged from one week to two months. If the library 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 to update applications to a newer library version beforehand. ## Package renamings As stipulated in the current deprecation policy, such renamings may happen 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 one year, and to ease its removal after the year, 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, moving a package from one module to another is akin to a removal immediately followed by an addition. It is handled by the removal procedure above with a one week initial notification period. ## Package additions Care shall be taken when adding packages that these are not already outdated or depending on outdated libraries, since such packages may cause considerable maintenance burden in the future. ## Cost of Reverting The GCD does not completely overturn the current deprecation policy; partially it only codifies existing practices that have developed over time when implementing the policy. It fixes steps to follow and delays to be respected, by shortening the existing delays for simple cases and lengthening them for more complex cases. 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 discussion period will show whether this has been reached. The procedure for notifying channel maintainers (and interested users) is not fully thought out yet. Is it possible and manageable to add a potentially large number of Codeberg accounts to a team without giving them privileges in the Guix repository? Could this team be notified automatically for deprecation issues without being mentioned explicitly in the issue body? Are there alternative or additional ideas for notification that would not add a burden on packagers trying to deprecate packages?
