From a591df482f2d7e226566a419649fdf8d4333a4d1 Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Tue, 5 May 2026 18:11:51 +0200 Subject: doc: Transcribe GCD 006. * doc/contributing.texi (Deprecation Policy): Update according to GCD 006. Change-Id: If48d74c8ed94f5040d842de03150a3ee673f841d --- doc/contributing.texi | 105 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 74 insertions(+), 31 deletions(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 6ad271cf432..0da29d4c68b 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -3216,7 +3216,10 @@ user survey before enacting a plan. @cindex package deprecation @item Package name changes When a package name changes, it must remain available under its old name -for @b{at least one year}. For example, @code{go-ipfs} was renamed to +for @b{at least six months}; the deprecation date should be stated in +a comment in the code to ease the final removal. + +For example, @code{go-ipfs} was renamed to @code{kubo} following a decision made upstream; to communicate the name change to users, the package module provided this definition: @@ -3240,44 +3243,84 @@ package name as deprecated. @cindex package removal policy @anchor{package-removal-policy} @item Package removal -Packages whose upstream developers have declared as having reached ``end -of life'' or being unmaintained may be removed; likewise, packages that -have been @b{failing to build for two months or more} may be removed. -There is no formal deprecation mechanism for this case, unless a -replacement exists, in which case the @code{define-deprecated-package} -macro mentioned above can be used. +How packages may be removed depends on their build status and on their +position in the package graph. +@itemize +@item Removal of packages that do not build + +A package that does not build becomes a removal candidate immediately. +A pull request removing such a package should be filed on Codeberg +with the @samp{deprecation} label. Additional justification for the +(non-)importance, obsolescence etc. of the package is welcome, but not +required. +Such a pull request may be merged @b{at least three weeks} later if there +is no opposition to the removal or if nobody has volunteered to repair the +affected packages. + +@item Removal of building packages + +There are various reasons why 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. + +@table @asis +@item +Removal candidates that are building leaf packages + +Leaf packages 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) should +not be removed unless there are particularly good reasons, such as +security implications. + +@item +Removal candidates that are building packages with dependents + +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. -If the package being removed is a ``leaf'' (no other packages depend on -it), it may be removed after a @b{one-month review period} of the patch -removing it (this applies even when the removal has additional -motivations such as security problems affecting the package). +@end table +@end itemize @quotation Note Learn about pending package removals by checking -@uref{https://codeberg.org/guix/guix/issues?labels=445131, issues and +@uref{https://codeberg.org/guix/guix/pulls?labels=445131, pull requests with the @samp{deprecation} label}. @end quotation -If the package has many dependent packages---as is the case for example with -Python version@tie{}2---the relevant team must propose a deprecation -removal agenda and seek consensus with other packagers for @b{at least -one month}. It may also invite feedback from the broader user -community, for example through a survey. Removal of all impacted -packages may be gradual, spanning multiple months, to accommodate all -use cases. - -When the package being removed is considered popular, whether or not it -is a leaf, its deprecation must be announced as an entry in -@code{etc/news.scm}. - -@item Package upgrade -In the case of packages with many dependents and/or many users, an -upgrade may be treated like the @emph{removal} of the previous version. - -Examples include major version upgrades of programming language -implementations, as we've seen above with Python, and major upgrades of -``big'' libraries such as Qt or GTK. +@item Moving packages between modules + +When a package is moved from one module to another one, the corresponding +variable @var{name} should be marked as deprecated in the old location +for @b{at least six months}, for instance by adding +@findex define-deprecated/public-alias +@lisp +(define-deprecated/public-alias @var{name} + (@@ (gnu packages @var{new-module} @var{name})) +@end lisp +in @var{gnu/packages/old-module.scm}. + +@item Package additions + +Packages submitted for inclusion must not fulfill the criteria to become +a removal candidate immediately after addition. + @cindex service deprecation @item Services -- cgit v1.2.3