[PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.

  • Done
  • quality assurance status badge
Details
10 participants
  • Andreas Enge
  • Greg Hogan
  • indieterminacy
  • Janneke Nieuwenhuizen
  • Konrad Hinsen
  • Ludovic Courtès
  • Maxim Cournoyer
  • Noé Lopez
  • pelzflorian (Florian Pelz)
  • Simon Tournier
Owner
unassigned
Submitted by
Ludovic Courtès
Severity
normal
Merged with
L
L
Ludovic Courtès wrote on 27 Aug 21:30 +0200
(address . guix-patches@gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
80f8b603ecd73cb9f46b1ea43797e143f16d2f17.1724785788.git.ludo@gnu.org
DRAFT: This is a starting point submitted for discussion.

* doc/contributing.texi (Deprecation Policy): New node.

Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee
---
doc/contributing.texi | 176 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 176 insertions(+)

Hello!

As promised long ago, here is an attempt to formalize a deprecation
policy, based on current unwritten practice.

Let’s discuss it with the goal of checking in an initial revision by
next month.

Thanks,
Ludo’.

Toggle diff (198 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73f7addbef..3c386f6510 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -34,6 +34,7 @@ Contributing
* Commit Access:: Pushing to the official repository.
* Reviewing the Work of Others:: Some guidelines for sharing reviews.
* Updating the Guix Package:: Updating the Guix package definition.
+* Deprecation Policy:: Commitments and tools for deprecation.
* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -3030,6 +3031,181 @@ Updating the Guix Package
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@node Deprecation Policy
+@section Deprecation Policy
+
+@cindex deprecation policy
+As any lively project with a broad scope, Guix changes all the time and
+all levels. Because it's user-extensible and programmable, incompatible
+changes can directly impact users and make their life harder. It is
+thus important to reduce user-visible incompatible changes to a minimum
+and, when such changes are deemed necessary, to clearly communicate them
+through a @dfn{deprecation period} so everyone can adapt with minimum
+hassle. This section defines the project's commitments for smooth
+deprecation and describes procedures and mechanisms to honor them.
+
+There are several ways to use Guix; how to handle deprecation will
+depend on each use case. Those can be roughly categorized like this:
+
+@itemize
+@item
+package management exclusively through the command line;
+
+@item
+advanced package management using the manifest and package interfaces;
+
+@item
+Home and System management, using the @code{operating-system} and/or
+@code{home-environment} interfaces together with the service interfaces;
+
+@item
+development of external tools that use programming interfaces such as
+the @code{(guix ...)} modules.
+@end itemize
+
+These use cases form a spectrum with varying degrees of coupling---from
+``distant'' to tightly coupled. Based on this insight, we define the
+following @dfn{deprecation policies} that we consider suitable for each
+of these levels.
+
+@table @asis
+@item Command-line tools
+Guix sub-commands should be thought of as remaining available
+``forever''. Once a Guix sub-command is to be removed, it should be
+deprecated first, and then remain available for at least one year after
+the first release that deprecated it.
+
+Deprecation should first be announced in the manual and as an entry in
+@file{etc/news.scm}; additional communication such as a blog post
+explaining the rationale is welcome. Months before the scheduled
+removal date, the command should print a warning explaining how to
+migrate. An example of this is the replacement of @command{guix
+environment} by @command{guix shell}, started in October
+2021@footnote{For more details on the @command{guix shell} transition,
+see
+@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
+
+Because of the broad impact of such a change, we recommend conducting a
+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 at least one year. 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:
+
+@findex deprecated-package
+@lisp
+(define-public go-ipfs
+ (deprecated-package "go-ipfs" kubo))
+@end lisp
+
+That way, someone running @command{guix install go-ipfs} or similar sees
+a deprecation warning mentioning the new name.
+
+@item Package removal
+Packages that their upstream developers have declared as having reach
+``end of life'' or being unmaintained may be removed. There is no
+formal deprecation mechanism for this case, unless a replacement exists,
+in which case the @code{deprecated-package} procedure mentioned above
+can be used.
+
+If the package being removed is a ``leaf'' (no other packages depend on
+it), it may be removed after a one-month review period of the patch
+removing it.
+
+If it 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 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}.
+
+@cindex service deprecation
+@item Services
+Changes to services for Guix Home and Guix System have a direct impact
+on user configuration. For a user, adjusting to interface changes is
+rarely rewarding, which is why any such change must be clearly
+communicated in advance through deprecation warnings and documentation.
+
+Renaming of variables related to service, home, or system configuration
+must be communicated for at least six months before removal using the
+@code{(guix deprecation)} mechanisms. For example, renaming of
+@code{murmur-configuration} to @code{mumble-server-configuration} was
+communicated through a series of definitions like this one:
+
+@findex define-deprecated/public-alias
+@lisp
+(define-deprecated/public-alias
+ murmur-configuration
+ mumble-server-configuration)
+@end lisp
+
+Procedures slated for removal may be defined like this:
+
+@findex define-deprecated
+@lisp
+(define-deprecated (elogind-service #:key (config (elogind-configuration)))
+ elogind-service-type
+ (service elogind-service-type config))
+@end lisp
+
+Record fields, notably fields of service configuration records, must
+follow a similar deprecation period. This is usually achieved through
+@i{ad hoc} means though. For example, the @code{hosts-file} field of
+@code{operating-system} was deprecated by adding a @code{sanitized}
+property that would emit a warning:
+
+@lisp
+(define-record-type* <operating-system>
+ ;; @dots{}
+ (hosts-file %operating-system-hosts-file ;deprecated
+ (default #f)
+ (sanitize warn-hosts-file-field-deprecation)))
+
+(define-deprecated (operating-system-hosts-file os)
+ hosts-service-type
+ (%operating-system-hosts-file os))
+@end lisp
+
+When deprecating interfaces in @code{operating-system},
+@code{home-environment}, @code{(gnu services)}, or any popular service,
+the deprecation must come with an entry in @code{etc/news.scm}.
+
+@cindex deprecation of programming interfaces
+@item Core interfaces
+Core programming interfaces, in particular the @code{(guix ...)}
+modules, may be relied on by a variety of external tools and channels.
+Any incompatible change must be formally deprecated with
+@code{define-deprecated}, as shown above, for at least one year before
+removal. The manual must clearly document the new interface and, except
+in obvious cases, explain how to migrate from the old one.
+
+As an example, the @code{build-expression->derivation} procedure was
+superseded by @code{gexp->derivation} and remained available as a
+deprecated symbol:
+
+@lisp
+(define-deprecated (build-expression->derivation store name exp
+ #:key @dots{})
+ gexp->derivation
+ @dots{})
+@end lisp
+
+Sometimes bindings are moved from one module to another. In those
+cases, bindings must be reexported from the original module for at least
+one year.
+@end table
+
+This section does not cover all possible situations but hopefully allows
+users to know what to expect and developers to stick to its spirit.
+Please email @email{guix-devel@@gnu.org} for any questions.
+
@cindex documentation
@node Writing Documentation
@section Writing Documentation

base-commit: a1d367d6ee8c1783ef94cebbc5f2ae3b7a08078d
--
2.45.2
L
L
Ludovic Courtès wrote on 28 Aug 16:31 +0200
control message for bug #72839
(address . control@debbugs.gnu.org)
87zfowk9bh.fsf@gnu.org
merge 72839 72840
quit
P
P
pelzflorian (Florian Pelz) wrote on 2 Sep 13:53 +0200
Re: [bug#72840] [PATCH RFC] DRAFT doc: Add “Dep recation Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
877cbunuf7.fsf@pelzflorian.de
Hello Ludo. Having a deprecation policy clarifies things. Thank you
for writing a good one!

Ludovic Courtès <ludo@gnu.org> writes:
Toggle quote (3 lines)
> +@item Package removal
> +Packages that their upstream developers have declared as having reach

typo: reached


Toggle quote (10 lines)
> +``end of life'' or being unmaintained may be removed. There is no
> +formal deprecation mechanism for this case, unless a replacement exists,
> +in which case the @code{deprecated-package} procedure mentioned above
> +can be used.
> +
> +If the package being removed is a ``leaf'' (no other packages depend on
> +it), it may be removed after a one-month review period of the patch
> +removing it.
> +

Could you also reference this one-month period in the Commit Access section,
where policy is one or two weeks?

Thinking of package removals for security reasons, it should be
clearer that this one-month period applies even in this case. (IMHO
some period should apply. It is the user’s decision to use software
despite security problems. We all know web browsers’ security track
record; not everone puts the web to use everywhere, but Guix
thankfully does ship web browsers.)


Toggle quote (15 lines)
> […]
> +@cindex deprecation of programming interfaces
> +@item Core interfaces
> +Core programming interfaces, in particular the @code{(guix ...)}
> +modules, may be relied on by a variety of external tools and channels.
> +Any incompatible change must be formally deprecated with

> +@code{define-deprecated}, as shown above, for at least one year before
> +removal. The manual must clearly document the new interface and, except
> +in obvious cases, explain how to migrate from the old one.
> +
> +As an example, the @code{build-expression->derivation} procedure was
> +superseded by @code{gexp->derivation} and remained available as a
> +deprecated symbol:

This cannot be an absolute truth. It is not always reasonable to make
changes bacwards-compatible. For example, the switch from xz
repacking to zstd repacking in recent core-updates did break
guile-manual in doc/build.scm and perhaps did break outside code, but
it was right nonetheless. Also Guix is in one big guix.git repository
so that we can make changes.

Regards,
Florian
L
L
Ludovic Courtès wrote on 5 Sep 23:26 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
87frqd6bcu.fsf_-_@gnu.org
Hi Florian,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

Toggle quote (3 lines)
> Hello Ludo. Having a deprecation policy clarifies things. Thank you
> for writing a good one!

Thanks for taking a look!

Toggle quote (8 lines)
>> +If the package being removed is a ``leaf'' (no other packages depend on
>> +it), it may be removed after a one-month review period of the patch
>> +removing it.
>> +
>
> Could you also reference this one-month period in the Commit Access section,
> where policy is one or two weeks?

Sure, done in v2 (sent separately).

Toggle quote (7 lines)
> Thinking of package removals for security reasons, it should be
> clearer that this one-month period applies even in this case. (IMHO
> some period should apply. It is the user’s decision to use software
> despite security problems. We all know web browsers’ security track
> record; not everone puts the web to use everywhere, but Guix
> thankfully does ship web browsers.)

Indeed; I tried to clarify that in v2.

Toggle quote (10 lines)
>> […]
>> +@cindex deprecation of programming interfaces
>> +@item Core interfaces
>> +Core programming interfaces, in particular the @code{(guix ...)}
>> +modules, may be relied on by a variety of external tools and channels.
>> +Any incompatible change must be formally deprecated with
>> +@code{define-deprecated}, as shown above, for at least one year before
>> +removal. The manual must clearly document the new interface and, except
>> +in obvious cases, explain how to migrate from the old one.

[...]

Toggle quote (7 lines)
> This cannot be an absolute truth. It is not always reasonable to make
> changes bacwards-compatible. For example, the switch from xz
> repacking to zstd repacking in recent core-updates did break
> guile-manual in doc/build.scm and perhaps did break outside code, but
> it was right nonetheless. Also Guix is in one big guix.git repository
> so that we can make changes.

Yes, I agree. But note that this paragraph is concerned with
programming interfaces, which would not cover the case you describe IMO
(though I understand this is debatable).

I thought about changing “must be formally deprecated” to “must be
formally deprecated […] unless the cost of doing so is considered
disproportionate”. But then it sounds like inviting Guix developers to
put their own interests first and significantly weakens this deprecation
“contract” with users. Maybe there are other ways to phrase it?

Also, the section ends with:

Toggle quote (3 lines)
> This section does not cover all possible situations but hopefully allows
> users to know what to expect and developers to stick to its spirit.

… which in my mind would cover situations like what you describe.

WDYT?

Thanks again for your feedback.

Ludo’.
Closed
L
L
Ludovic Courtès wrote on 5 Sep 23:31 +0200
[PATCH RFC v2] doc: Add “Deprecation Poli cy” section.
(address . 72840@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
53d897cec60ae13a22de486ba37604ab99e65fe8.1725571691.git.ludo@gnu.org
* doc/contributing.texi (Deprecation Policy): New node.
(Commit Access): Link to ‘package-removal-policy’.

Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee
---
doc/contributing.texi | 188 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 185 insertions(+), 3 deletions(-)

Changes compared to v1:

• Fixed typo reported by Florian;

• Adding cross-reference in “Commit Access” section;

• Typeset review/deprecation durations in boldface;

• Clarified that the package removal policy also applies when
removal is motivated by security reasons.

Ludo’.

Toggle diff (217 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73f7addbef..f8c2b5c245 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -34,6 +34,7 @@ Contributing
* Commit Access:: Pushing to the official repository.
* Reviewing the Work of Others:: Some guidelines for sharing reviews.
* Updating the Guix Package:: Updating the Guix package definition.
+* Deprecation Policy:: Commitments and tools for deprecation.
* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -2805,9 +2806,11 @@ Commit Access
repository, especially for the @code{master} branch.
If you're committing and pushing your own changes, try and wait at least
-one week (two weeks for more significant changes) after you send them
-for review. After this, if no one else is available to review them and
-if you're confident about the changes, it's OK to commit.
+one week (two weeks for more significant changes, up to one month for
+changes such as removing a package---@pxref{package-removal-policy,
+Package Removal}) after you send them for review. After this, if no one
+else is available to review them and if you're confident about the
+changes, it's OK to commit.
When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g.,
@@ -3030,6 +3033,185 @@ Updating the Guix Package
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@node Deprecation Policy
+@section Deprecation Policy
+
+@cindex deprecation policy
+As any lively project with a broad scope, Guix changes all the time and
+all levels. Because it's user-extensible and programmable, incompatible
+changes can directly impact users and make their life harder. It is
+thus important to reduce user-visible incompatible changes to a minimum
+and, when such changes are deemed necessary, to clearly communicate them
+through a @dfn{deprecation period} so everyone can adapt with minimum
+hassle. This section defines the project's commitments for smooth
+deprecation and describes procedures and mechanisms to honor them.
+
+There are several ways to use Guix; how to handle deprecation will
+depend on each use case. Those can be roughly categorized like this:
+
+@itemize
+@item
+package management exclusively through the command line;
+
+@item
+advanced package management using the manifest and package interfaces;
+
+@item
+Home and System management, using the @code{operating-system} and/or
+@code{home-environment} interfaces together with the service interfaces;
+
+@item
+development of external tools that use programming interfaces such as
+the @code{(guix ...)} modules.
+@end itemize
+
+These use cases form a spectrum with varying degrees of coupling---from
+``distant'' to tightly coupled. Based on this insight, we define the
+following @dfn{deprecation policies} that we consider suitable for each
+of these levels.
+
+@table @asis
+@item Command-line tools
+Guix sub-commands should be thought of as remaining available
+``forever''. Once a Guix sub-command is to be removed, it should be
+deprecated first, and then remain available for @b{at least one year}
+after the first release that deprecated it.
+
+Deprecation should first be announced in the manual and as an entry in
+@file{etc/news.scm}; additional communication such as a blog post
+explaining the rationale is welcome. Months before the scheduled
+removal date, the command should print a warning explaining how to
+migrate. An example of this is the replacement of @command{guix
+environment} by @command{guix shell}, started in October
+2021@footnote{For more details on the @command{guix shell} transition,
+see
+@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
+
+Because of the broad impact of such a change, we recommend conducting a
+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
+@code{kubo} following a decision made upstream; to communicate the name
+change to users, the package module provided this definition:
+
+@findex deprecated-package
+@lisp
+(define-public go-ipfs
+ (deprecated-package "go-ipfs" kubo))
+@end lisp
+
+That way, someone running @command{guix install go-ipfs} or similar sees
+a deprecation warning mentioning the new name.
+
+@cindex package removal policy
+@anchor{package-removal-policy}
+@item Package removal
+Packages that their upstream developers have declared as having reached
+``end of life'' or being unmaintained may be removed. There is no
+formal deprecation mechanism for this case, unless a replacement exists,
+in which case the @code{deprecated-package} procedure mentioned above
+can be used.
+
+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).
+
+If it 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}.
+
+@cindex service deprecation
+@item Services
+Changes to services for Guix Home and Guix System have a direct impact
+on user configuration. For a user, adjusting to interface changes is
+rarely rewarding, which is why any such change must be clearly
+communicated in advance through deprecation warnings and documentation.
+
+Renaming of variables related to service, home, or system configuration
+must be communicated for at least six months before removal using the
+@code{(guix deprecation)} mechanisms. For example, renaming of
+@code{murmur-configuration} to @code{mumble-server-configuration} was
+communicated through a series of definitions like this one:
+
+@findex define-deprecated/public-alias
+@lisp
+(define-deprecated/public-alias
+ murmur-configuration
+ mumble-server-configuration)
+@end lisp
+
+Procedures slated for removal may be defined like this:
+
+@findex define-deprecated
+@lisp
+(define-deprecated (elogind-service #:key (config (elogind-configuration)))
+ elogind-service-type
+ (service elogind-service-type config))
+@end lisp
+
+Record fields, notably fields of service configuration records, must
+follow a similar deprecation period. This is usually achieved through
+@i{ad hoc} means though. For example, the @code{hosts-file} field of
+@code{operating-system} was deprecated by adding a @code{sanitized}
+property that would emit a warning:
+
+@lisp
+(define-record-type* <operating-system>
+ ;; @dots{}
+ (hosts-file %operating-system-hosts-file ;deprecated
+ (default #f)
+ (sanitize warn-hosts-file-field-deprecation)))
+
+(define-deprecated (operating-system-hosts-file os)
+ hosts-service-type
+ (%operating-system-hosts-file os))
+@end lisp
+
+When deprecating interfaces in @code{operating-system},
+@code{home-environment}, @code{(gnu services)}, or any popular service,
+the deprecation must come with an entry in @code{etc/news.scm}.
+
+@cindex deprecation of programming interfaces
+@item Core interfaces
+Core programming interfaces, in particular the @code{(guix ...)}
+modules, may be relied on by a variety of external tools and channels.
+Any incompatible change must be formally deprecated with
+@code{define-deprecated}, as shown above, for @b{at least one year}
+before removal. The manual must clearly document the new interface and,
+except in obvious cases, explain how to migrate from the old one.
+
+As an example, the @code{build-expression->derivation} procedure was
+superseded by @code{gexp->derivation} and remained available as a
+deprecated symbol:
+
+@lisp
+(define-deprecated (build-expression->derivation store name exp
+ #:key @dots{})
+ gexp->derivation
+ @dots{})
+@end lisp
+
+Sometimes bindings are moved from one module to another. In those
+cases, bindings must be reexported from the original module for at least
+one year.
+@end table
+
+This section does not cover all possible situations but hopefully allows
+users to know what to expect and developers to stick to its spirit.
+Please email @email{guix-devel@@gnu.org} for any questions.
+
@cindex documentation
@node Writing Documentation
@section Writing Documentation

base-commit: 993d6d2e7be4dac738629c76a51058f4dc5bc449
--
2.45.2
L
L
Ludovic Courtès wrote on 5 Sep 23:32 +0200
control message for bug #72840
(address . control@debbugs.gnu.org)
87bk116b2p.fsf@gnu.org
reopen 72840
tags 72840 - fixed patch
quit
M
M
Maxim Cournoyer wrote on 11 Sep 09:04 +0200
Re: [bug#72840] [PATCH RFC v2] doc: Add “Deprec ation Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
8734m63c4f.fsf@gmail.com
Hi Ludovic,

Ludovic Courtès <ludo@gnu.org> writes:

Toggle quote (43 lines)
> * doc/contributing.texi (Deprecation Policy): New node.
> (Commit Access): Link to ‘package-removal-policy’.
>
> Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee
> ---
> doc/contributing.texi | 188 +++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 185 insertions(+), 3 deletions(-)
>
> Changes compared to v1:
>
> • Fixed typo reported by Florian;
>
> • Adding cross-reference in “Commit Access” section;
>
> • Typeset review/deprecation durations in boldface;
>
> • Clarified that the package removal policy also applies when
> removal is motivated by security reasons.
>
> Ludo’.
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 73f7addbef..f8c2b5c245 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -34,6 +34,7 @@ Contributing
> * Commit Access:: Pushing to the official repository.
> * Reviewing the Work of Others:: Some guidelines for sharing reviews.
> * Updating the Guix Package:: Updating the Guix package definition.
> +* Deprecation Policy:: Commitments and tools for deprecation.
> * Writing Documentation:: Improving documentation in GNU Guix.
> * Translating Guix:: Make Guix speak your native language.
> @end menu
> @@ -2805,9 +2806,11 @@ Commit Access
> repository, especially for the @code{master} branch.
>
> If you're committing and pushing your own changes, try and wait at least
> -one week (two weeks for more significant changes) after you send them
> -for review. After this, if no one else is available to review them and
> -if you're confident about the changes, it's OK to commit.
> +one week (two weeks for more significant changes, up to one month for
> +changes such as removing a package---@pxref{package-removal-policy,
> +Package Removal}) after you send them for review. After this, if no one
^ two spaces convention
Toggle quote (16 lines)
> +else is available to review them and if you're confident about the
> +changes, it's OK to commit.
>
> When pushing a commit on behalf of somebody else, please add a
> @code{Signed-off-by} line at the end of the commit log message---e.g.,
> @@ -3030,6 +3033,185 @@ Updating the Guix Package
> this variable is set, the updated package source is also added to the
> store. This is used as part of the release process of Guix.
>
> +@node Deprecation Policy
> +@section Deprecation Policy
> +
> +@cindex deprecation policy
> +As any lively project with a broad scope, Guix changes all the time and
> +all levels. Because it's user-extensible and programmable, incompatible

Perhaps 'at all the time and *at* all levels' ? It reads better for me.

Toggle quote (72 lines)
> +changes can directly impact users and make their life harder. It is
> +thus important to reduce user-visible incompatible changes to a minimum
> +and, when such changes are deemed necessary, to clearly communicate them
> +through a @dfn{deprecation period} so everyone can adapt with minimum
> +hassle. This section defines the project's commitments for smooth
> +deprecation and describes procedures and mechanisms to honor them.
> +
> +There are several ways to use Guix; how to handle deprecation will
> +depend on each use case. Those can be roughly categorized like this:
> +
> +@itemize
> +@item
> +package management exclusively through the command line;
> +
> +@item
> +advanced package management using the manifest and package interfaces;
> +
> +@item
> +Home and System management, using the @code{operating-system} and/or
> +@code{home-environment} interfaces together with the service interfaces;
> +
> +@item
> +development of external tools that use programming interfaces such as
> +the @code{(guix ...)} modules.
> +@end itemize
> +
> +These use cases form a spectrum with varying degrees of coupling---from
> +``distant'' to tightly coupled. Based on this insight, we define the
> +following @dfn{deprecation policies} that we consider suitable for each
> +of these levels.
> +
> +@table @asis
> +@item Command-line tools
> +Guix sub-commands should be thought of as remaining available
> +``forever''. Once a Guix sub-command is to be removed, it should be
> +deprecated first, and then remain available for @b{at least one year}
> +after the first release that deprecated it.
> +
> +Deprecation should first be announced in the manual and as an entry in
> +@file{etc/news.scm}; additional communication such as a blog post
> +explaining the rationale is welcome. Months before the scheduled
> +removal date, the command should print a warning explaining how to
> +migrate. An example of this is the replacement of @command{guix
> +environment} by @command{guix shell}, started in October
> +2021@footnote{For more details on the @command{guix shell} transition,
> +see
> +@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
> +
> +Because of the broad impact of such a change, we recommend conducting a
> +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
> +@code{kubo} following a decision made upstream; to communicate the name
> +change to users, the package module provided this definition:
> +
> +@findex deprecated-package
> +@lisp
> +(define-public go-ipfs
> + (deprecated-package "go-ipfs" kubo))
> +@end lisp
> +
> +That way, someone running @command{guix install go-ipfs} or similar sees
> +a deprecation warning mentioning the new name.
> +
> +@cindex package removal policy
> +@anchor{package-removal-policy}
> +@item Package removal
> +Packages that their upstream developers have declared as having reached

s/that their/whose/

Toggle quote (102 lines)
> +``end of life'' or being unmaintained may be removed. There is no
> +formal deprecation mechanism for this case, unless a replacement exists,
> +in which case the @code{deprecated-package} procedure mentioned above
> +can be used.
> +
> +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).
> +
> +If it 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}.
> +
> +@cindex service deprecation
> +@item Services
> +Changes to services for Guix Home and Guix System have a direct impact
> +on user configuration. For a user, adjusting to interface changes is
> +rarely rewarding, which is why any such change must be clearly
> +communicated in advance through deprecation warnings and documentation.
> +
> +Renaming of variables related to service, home, or system configuration
> +must be communicated for at least six months before removal using the
> +@code{(guix deprecation)} mechanisms. For example, renaming of
> +@code{murmur-configuration} to @code{mumble-server-configuration} was
> +communicated through a series of definitions like this one:
> +
> +@findex define-deprecated/public-alias
> +@lisp
> +(define-deprecated/public-alias
> + murmur-configuration
> + mumble-server-configuration)
> +@end lisp
> +
> +Procedures slated for removal may be defined like this:
> +
> +@findex define-deprecated
> +@lisp
> +(define-deprecated (elogind-service #:key (config (elogind-configuration)))
> + elogind-service-type
> + (service elogind-service-type config))
> +@end lisp
> +
> +Record fields, notably fields of service configuration records, must
> +follow a similar deprecation period. This is usually achieved through
> +@i{ad hoc} means though. For example, the @code{hosts-file} field of
> +@code{operating-system} was deprecated by adding a @code{sanitized}
> +property that would emit a warning:
> +
> +@lisp
> +(define-record-type* <operating-system>
> + ;; @dots{}
> + (hosts-file %operating-system-hosts-file ;deprecated
> + (default #f)
> + (sanitize warn-hosts-file-field-deprecation)))
> +
> +(define-deprecated (operating-system-hosts-file os)
> + hosts-service-type
> + (%operating-system-hosts-file os))
> +@end lisp
> +
> +When deprecating interfaces in @code{operating-system},
> +@code{home-environment}, @code{(gnu services)}, or any popular service,
> +the deprecation must come with an entry in @code{etc/news.scm}.
> +
> +@cindex deprecation of programming interfaces
> +@item Core interfaces
> +Core programming interfaces, in particular the @code{(guix ...)}
> +modules, may be relied on by a variety of external tools and channels.
> +Any incompatible change must be formally deprecated with
> +@code{define-deprecated}, as shown above, for @b{at least one year}
> +before removal. The manual must clearly document the new interface and,
> +except in obvious cases, explain how to migrate from the old one.
> +
> +As an example, the @code{build-expression->derivation} procedure was
> +superseded by @code{gexp->derivation} and remained available as a
> +deprecated symbol:
> +
> +@lisp
> +(define-deprecated (build-expression->derivation store name exp
> + #:key @dots{})
> + gexp->derivation
> + @dots{})
> +@end lisp
> +
> +Sometimes bindings are moved from one module to another. In those
> +cases, bindings must be reexported from the original module for at least
> +one year.
> +@end table
> +
> +This section does not cover all possible situations but hopefully allows
> +users to know what to expect and developers to stick to its spirit.
> +Please email @email{guix-devel@@gnu.org} for any questions.

Thanks for taking the time to write this down. It'll be useful to many
I'm sure, including myself.

Apart from the small things I've spotted above, it looks like a pretty
good starting ground for a deprecation policy.

One thought I'm having right now is that it would be cool if all these
deprecation mechanism offered in the (guix deprecation) module were
fully documented in our manual, and could be referred to from the above
section/text for extra information; but this can be done in the future.

--
Thanks,
Maxim
L
L
Ludovic Courtès wrote on 11 Sep 12:11 +0200
[PATCH RFC v3] doc: Add “Deprecation Poli cy” section.
(address . 72840@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
902c544b5298617c2ed45af8d672130bc9b1a2e3.1726049102.git.ludo@gnu.org
* doc/contributing.texi (Deprecation Policy): New node.
(Commit Access): Link to ‘package-removal-policy’.

Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee
---
doc/contributing.texi | 189 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 186 insertions(+), 3 deletions(-)

Changes compared to v2: fixed typos reported by Maxim Cournoyer.

Toggle diff (218 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73f7addbef..f713765357 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -34,6 +34,7 @@ Contributing
* Commit Access:: Pushing to the official repository.
* Reviewing the Work of Others:: Some guidelines for sharing reviews.
* Updating the Guix Package:: Updating the Guix package definition.
+* Deprecation Policy:: Commitments and tools for deprecation.
* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -2805,9 +2806,11 @@ Commit Access
repository, especially for the @code{master} branch.
If you're committing and pushing your own changes, try and wait at least
-one week (two weeks for more significant changes) after you send them
-for review. After this, if no one else is available to review them and
-if you're confident about the changes, it's OK to commit.
+one week (two weeks for more significant changes, up to one month for
+changes such as removing a package---@pxref{package-removal-policy,
+Package Removal}) after you send them for review. After this, if no one
+else is available to review them and if you're confident about the
+changes, it's OK to commit.
When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g.,
@@ -3030,6 +3033,186 @@ Updating the Guix Package
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@node Deprecation Policy
+@section Deprecation Policy
+
+@cindex deprecation policy
+As any lively project with a broad scope, Guix changes all the time and
+at all levels. Because it's user-extensible and programmable,
+incompatible changes can directly impact users and make their life
+harder. It is thus important to reduce user-visible incompatible
+changes to a minimum and, when such changes are deemed necessary, to
+clearly communicate them through a @dfn{deprecation period} so everyone
+can adapt with minimum hassle. This section defines the project's
+commitments for smooth deprecation and describes procedures and
+mechanisms to honor them.
+
+There are several ways to use Guix; how to handle deprecation will
+depend on each use case. Those can be roughly categorized like this:
+
+@itemize
+@item
+package management exclusively through the command line;
+
+@item
+advanced package management using the manifest and package interfaces;
+
+@item
+Home and System management, using the @code{operating-system} and/or
+@code{home-environment} interfaces together with the service interfaces;
+
+@item
+development of external tools that use programming interfaces such as
+the @code{(guix ...)} modules.
+@end itemize
+
+These use cases form a spectrum with varying degrees of coupling---from
+``distant'' to tightly coupled. Based on this insight, we define the
+following @dfn{deprecation policies} that we consider suitable for each
+of these levels.
+
+@table @asis
+@item Command-line tools
+Guix sub-commands should be thought of as remaining available
+``forever''. Once a Guix sub-command is to be removed, it should be
+deprecated first, and then remain available for @b{at least one year}
+after the first release that deprecated it.
+
+Deprecation should first be announced in the manual and as an entry in
+@file{etc/news.scm}; additional communication such as a blog post
+explaining the rationale is welcome. Months before the scheduled
+removal date, the command should print a warning explaining how to
+migrate. An example of this is the replacement of @command{guix
+environment} by @command{guix shell}, started in October
+2021@footnote{For more details on the @command{guix shell} transition,
+see
+@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
+
+Because of the broad impact of such a change, we recommend conducting a
+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
+@code{kubo} following a decision made upstream; to communicate the name
+change to users, the package module provided this definition:
+
+@findex deprecated-package
+@lisp
+(define-public go-ipfs
+ (deprecated-package "go-ipfs" kubo))
+@end lisp
+
+That way, someone running @command{guix install go-ipfs} or similar sees
+a deprecation warning mentioning the new name.
+
+@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. There is no formal
+deprecation mechanism for this case, unless a replacement exists, in
+which case the @code{deprecated-package} procedure mentioned above can
+be used.
+
+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).
+
+If it 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}.
+
+@cindex service deprecation
+@item Services
+Changes to services for Guix Home and Guix System have a direct impact
+on user configuration. For a user, adjusting to interface changes is
+rarely rewarding, which is why any such change must be clearly
+communicated in advance through deprecation warnings and documentation.
+
+Renaming of variables related to service, home, or system configuration
+must be communicated for at least six months before removal using the
+@code{(guix deprecation)} mechanisms. For example, renaming of
+@code{murmur-configuration} to @code{mumble-server-configuration} was
+communicated through a series of definitions like this one:
+
+@findex define-deprecated/public-alias
+@lisp
+(define-deprecated/public-alias
+ murmur-configuration
+ mumble-server-configuration)
+@end lisp
+
+Procedures slated for removal may be defined like this:
+
+@findex define-deprecated
+@lisp
+(define-deprecated (elogind-service #:key (config (elogind-configuration)))
+ elogind-service-type
+ (service elogind-service-type config))
+@end lisp
+
+Record fields, notably fields of service configuration records, must
+follow a similar deprecation period. This is usually achieved through
+@i{ad hoc} means though. For example, the @code{hosts-file} field of
+@code{operating-system} was deprecated by adding a @code{sanitized}
+property that would emit a warning:
+
+@lisp
+(define-record-type* <operating-system>
+ ;; @dots{}
+ (hosts-file %operating-system-hosts-file ;deprecated
+ (default #f)
+ (sanitize warn-hosts-file-field-deprecation)))
+
+(define-deprecated (operating-system-hosts-file os)
+ hosts-service-type
+ (%operating-system-hosts-file os))
+@end lisp
+
+When deprecating interfaces in @code{operating-system},
+@code{home-environment}, @code{(gnu services)}, or any popular service,
+the deprecation must come with an entry in @code{etc/news.scm}.
+
+@cindex deprecation of programming interfaces
+@item Core interfaces
+Core programming interfaces, in particular the @code{(guix ...)}
+modules, may be relied on by a variety of external tools and channels.
+Any incompatible change must be formally deprecated with
+@code{define-deprecated}, as shown above, for @b{at least one year}
+before removal. The manual must clearly document the new interface and,
+except in obvious cases, explain how to migrate from the old one.
+
+As an example, the @code{build-expression->derivation} procedure was
+superseded by @code{gexp->derivation} and remained available as a
+deprecated symbol:
+
+@lisp
+(define-deprecated (build-expression->derivation store name exp
+ #:key @dots{})
+ gexp->derivation
+ @dots{})
+@end lisp
+
+Sometimes bindings are moved from one module to another. In those
+cases, bindings must be reexported from the original module for at least
+one year.
+@end table
+
+This section does not cover all possible situations but hopefully allows
+users to know what to expect and developers to stick to its spirit.
+Please email @email{guix-devel@@gnu.org} for any questions.
+
@cindex documentation
@node Writing Documentation
@section Writing Documentation

base-commit: 637ca78f513fac15284403c0d3af64492ea832a1
--
2.46.0
L
L
Ludovic Courtès wrote on 11 Sep 12:11 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . Maxim Cournoyer)(address . maxim.cournoyer@gmail.com)
8734m67b4m.fsf_-_@gnu.org
Hello,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

Toggle quote (6 lines)
> Thanks for taking the time to write this down. It'll be useful to many
> I'm sure, including myself.
>
> Apart from the small things I've spotted above, it looks like a pretty
> good starting ground for a deprecation policy.

Coolio. I’ve sent v3 fixing the typos you reported.

Let’s wait for another week or so to give people a chance to comment.

Toggle quote (5 lines)
> One thought I'm having right now is that it would be cool if all these
> deprecation mechanism offered in the (guix deprecation) module were
> fully documented in our manual, and could be referred to from the above
> section/text for extra information; but this can be done in the future.

Right. At least ‘deprecated-package’, ‘define-deprecated’, etc. will
now have an index entry.

Thanks for taking the time to comment!

Ludo’.
N
N
Noé Lopez wrote on 11 Sep 20:30 +0200
[PATCH RFC] DRAFT doc: Add “Deprecation Policy ” section.
(address . 72840@debbugs.gnu.org)
<87mskexcue.fsf@>
Thanks for writing this,

A few things come to mind:

– How do we remember to delete something after one year of deprecation?
Should the deprecation date be noted with the deprecation to easily see?

– There is no policy for updating packages through major versions, IMO
this should be the same as deleting and the previous version should be
kept for a while, at least for the time for dependencies to update
upstream.

Toggle quote (5 lines)
>+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).

– Why do « leaves » get removed at all? The dependents could be
users that installed it in their profiles or manifests, one month
seems very low.

Overall it makes sense so thanks again for documenting this,
Noé

PS: RFCs don’t get announced to guix-devel? I only found out about this
from mastodon.
K
K
Konrad Hinsen wrote on 11 Sep 21:49 +0200
Deprecation policy
(address . 72840@debbugs.gnu.org)
m1ldzyj7i1.fsf@fastmail.net
Hi everyone,

It's good to have an explicit deprecation policy, thanks for writing
this!

Overall it looks good. I share Noé's concerns about breaking changes in
packages. If removing a package is subject to the deprecation policy,
then updating a package to an incompatible version should be handled the
same way. But it is of course much more difficult to detect, for the
packager and even more so for the Guix maintainers.

There's also a use case missing in the list in the beginning: Guix as a
dependency of some other software, which in the worst case is no longer
maintained. Users of such software may not even be aware of depending on
Guix, and thus not follow Guix news at all. The number of such programs
is probably close to zero right now, but I bet it won't remain
zero. Every piece of software becomes someone else's dependency one day,
at the latest during the next metasystem transition (see the last part
of my talk in Montpellier last year

This is certainly not an urgent problem, but an interesting one, so
worth thinking about.

Finally, I wonder about the practicalities. Who will watch out for
potential violations of this policy, and how? It doesn't look like an
easy task. In particular detecting "user-visible incompatible changes".

Cheers,
Konrad.
M
M
Maxim Cournoyer wrote on 12 Sep 02:40 +0200
Re: [bug#72840] [PATCH RFC v3] doc: Add “Deprec ation Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
87o74tyaa0.fsf@gmail.com
Hi,

Ludovic Courtès <ludo@gnu.org> writes:

Toggle quote (5 lines)
> * doc/contributing.texi (Deprecation Policy): New node.
> (Commit Access): Link to ‘package-removal-policy’.
>
> Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee

Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail>

--
Thanks,
Maxim
G
G
Greg Hogan wrote on 12 Sep 17:39 +0200
Re: [bug#72840] [PATCH RFC] DRAFT doc: Add “Deprec ation Policy” section.
(name . Noé Lopez)(address . noe@xn--no-cja.eu)(address . 72840@debbugs.gnu.org)
CA+3U0ZkDHm+bQ7R_qO0keQkzxny5EN7u2TZf-2an4UYXtvasCg@mail.gmail.com
On Wed, Sep 11, 2024 at 2:33?PM Noé Lopez via Guix-patches via
<guix-patches@gnu.org> wrote:
Toggle quote (6 lines)
>
> – There is no policy for updating packages through major versions, IMO
> this should be the same as deleting and the previous version should be
> kept for a while, at least for the time for dependencies to update
> upstream.

Internal package conflicts result in broken builds. External dependent
projects can simply remain on their current Guix commit and delay
upgrading until compatible with the updated API.

Toggle quote (9 lines)
> >+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).
>
> – Why do « leaves » get removed at all? The dependents could be
> users that installed it in their profiles or manifests, one month
> seems very low.

If a package has failed to build for and not been updated in a long
time then who would be using it? The package source will be available
in the git history in case someone would like to resurrect it at a
later time.

Greg
L
L
Ludovic Courtès wrote on 13 Sep 19:23 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . Noé Lopez)(address . noe@xn--no-cja.eu)(address . 72840@debbugs.gnu.org)
87plp7fox1.fsf_-_@gnu.org
Hi,

Noé Lopez <noe@noé.eu> skribis:

Toggle quote (3 lines)
> – How do we remember to delete something after one year of deprecation?
> Should the deprecation date be noted with the deprecation to easily see?

What I and probably others did in the past was to ‘git annotate’ files
to see when a deprecation was added and whether it could “reasonably” be
deleted (though we had no formal rule).

We can always do that, but adding a comment as you suggest is even
better.

Toggle quote (5 lines)
> – There is no policy for updating packages through major versions, IMO
> this should be the same as deleting and the previous version should be
> kept for a while, at least for the time for dependencies to update
> upstream.

Interesting point.

For many packages, a major version upgrade goes unnoticed and a
deprecation period of the previous major series wouldn’t be useful.

But for some (interpreters and compilers, “big” libraries/frameworks
like Qt or GTK, and perhaps a few applications), there’s definitely
going to be a need for both the old and new major series for some time.

I’m not sure how to codify that though. Maybe the best we can do is to
state that different situations exist and that “some” major package
upgrades may require a deprecation period for the older major series?

Toggle quote (9 lines)
>>+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).
>
> – Why do « leaves » get removed at all? The dependents could be
> users that installed it in their profiles or manifests, one month
> seems very low.

This paragraph talks about packages that are unmaintained or EOL
upstream. What it says is that such packages could be removed, at the
soonest, one month after they have become umaintained/EOL upstream.

The reasons we’d want to remove such packages is to clean up the package
collection (every package adds to the overall maintenance cost) and to
avoid steering users towards unmaintained and possibly insecure
software.

Is one-month after upstream too short? I’d say “no”, but we can
discuss.

Two things to keep in mind in this discussion: (1) the policy does not
state an obligation to remove those packages, and (2) packages remain
available “forever” for those who need it via ‘time-machine’.

Toggle quote (3 lines)
> PS: RFCs don’t get announced to guix-devel? I only found out about this
> from mastodon.

My bad! I thought I had Cc’d guix-devel, but apparently not? (Did the
‘send-email’ hook override the ‘Cc:’ or ‘X-Debbugs-Cc:’ header I had
put?)

Ludo’.
L
L
Ludovic Courtès wrote on 13 Sep 19:32 +0200
(name . Konrad Hinsen)(address . konrad.hinsen@fastmail.net)(address . 72840@debbugs.gnu.org)
87frq3foi5.fsf_-_@gnu.org
Hi Konrad,

Konrad Hinsen <konrad.hinsen@fastmail.net> skribis:

Toggle quote (6 lines)
> Overall it looks good. I share Noé's concerns about breaking changes in
> packages. If removing a package is subject to the deprecation policy,
> then updating a package to an incompatible version should be handled the
> same way. But it is of course much more difficult to detect, for the
> packager and even more so for the Guix maintainers.

Right; I agree this should be mentioned.

Toggle quote (10 lines)
> There's also a use case missing in the list in the beginning: Guix as a
> dependency of some other software, which in the worst case is no longer
> maintained. Users of such software may not even be aware of depending on
> Guix, and thus not follow Guix news at all. The number of such programs
> is probably close to zero right now, but I bet it won't remain
> zero. Every piece of software becomes someone else's dependency one day,
> at the latest during the next metasystem transition (see the last part
> of my talk in Montpellier last year
> (https://hpc.guix.info/events/2023/workshop/program/#caring-for-your-environment-s-)

I think this is covered by the last point:

+development of external tools that use programming interfaces such as
+the @code{(guix ...)} modules.

There are quite a few actually: the CI/QA tools, package browsers like
hpcguix-web, the Guix Workflow Language, Guix-Jupyter, rde, etc.

[...]

Toggle quote (4 lines)
> Finally, I wonder about the practicalities. Who will watch out for
> potential violations of this policy, and how? It doesn't look like an
> easy task. In particular detecting "user-visible incompatible changes".

As drafted here, there’s no enforcement and nobody having the duty of
looking for violations and taking action.

I view it as binding though. If a user complains that their favorite
package as been removed in violation of the policy, then we as a
community should review the claim and reinstate the package, unless it
violates “higher principles” in the project (that would need to be more
clearly defined too, but one of them would be: we mistakenly packaged
non-free software or material that we’re not allowed to distribute for
some reason).

I’ll think about ways to word it, but I’m happy to take other people’s
suggestions.

Thanks for your feedback,
Ludo’.
L
L
Ludovic Courtès wrote on 13 Sep 19:38 +0200
(name . Simon Tournier)(address . zimon.toutoune@gmail.com)
87zfobe9on.fsf_-_@gnu.org
Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

Toggle quote (3 lines)
> …Well, I’m just aware of this only now – thanks mastodon! Why only
> guix-patches and not guix-devel? Or do I also missed it?

My bad; as I told Noé, I thought I did advertise it on guix-devel, but
apparently not.

Toggle quote (2 lines)
> BTW, that’s the typical subject for a RFC [1], IMHO. :-)

Sure.

Toggle quote (5 lines)
> Why not try to push for crossing the final line of the RFC process first
> and make this as the first? ;-)
>
> 1: https://issues.guix.gnu.org/66844

That’s a question for you no?

I like to push things past the finish line in a timely fashion, so I
wouldn’t want this to be blocked by the RFC process definition process
(the process of defining the process…).

I already commented on the proposed RFC process. I’m happy to further
contribute or even take the lead eventually when time permits, if you’d
like to pass it on. It’s clearly the missing piece here. We’ll get
there!

Ludo’.
S
S
Simon Tournier wrote on 13 Sep 20:11 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depreca tion Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
CAJ3okZ2xyRedDzPucqBKzBbFGcN3pJFu1aaz6C2C2Dh3r=BDSQ@mail.gmail.com
Hi Ludo,

On Fri, 13 Sept 2024 at 19:38, Ludovic Courtès <ludo@gnu.org> wrote:

Toggle quote (2 lines)
> That’s a question for you no?

Yes and no. :-)

Yes because I sent the first draft, so it's partly my duty.

No because changes and especially collective practices are not only on
the shoulders of one. Is the motivation, time or energy of only one
person the bottleneck of a common willing?

Anyway.

Toggle quote (5 lines)
> I already commented on the proposed RFC process. I’m happy to further
> contribute or even take the lead eventually when time permits, if you’d
> like to pass it on. It’s clearly the missing piece here. We’ll get
> there!

It is a good example why Co-Supporter(s) as described by the RFC
process is a strong requirement. ;-) And there is none...

Anyway, I will do my best for resuming.

Cheers,
simon
I
I
indieterminacy wrote on 13 Sep 22:57 +0200
[PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.
(address . 72840@debbugs.gnu.org)
3130f45aaef0b424689f4c91a8dde943@libre.brussels
It may be that Im lacking a little experience,
but Id assume that the categories outlined earlier probably require
different timeframes:

A year feels a little arbitrary.

For example, Ive found it a little frustrating using randomly scoured
Guix snippets -
only to then find that at the moment of utilization that I get a WARNING
without much context.

Am I the only one who feels undermined and demotivated by information
which hits me over the head with WARNINGS?

Ive had this using elogin-service (cited before):

Perhaps additionally there need to be pointers to real VCS repos,
pinpointing a commit providing the migration inside a living
repo/infrastructure?

Such examples would be constructively showing how the change is
achievable,
and could be empowering through assurance and learning.

And if such /Appreciations/ cannot be found in the wild and covering
enough common adaptations, then perhaps a Depreciation is too soon?

Heck, a REASSURANCE printed following a reconfigure would be gravy!
Even better, Guix promising me a LIMERICK if I adapted off foobar within
24 hours would work.

Additionally, its worth pointing out that Im slowly adapting my parsing
approaches to be more commensurate with a form of modern hermeneutics.

I have been intrigued by how the language inside a setup like Guix
adapts over time.
As such, the topic of how Guix grammars evolve would be worth
documenting.

Practically, this could one day result in very old discourse from out of
date mailinglist or Debugs conversations being transformed into more
recent grammars to solve contemporary issues or suggest precedent when
evaluating a patch.

Regards,


Jonathan
J
J
Janneke Nieuwenhuizen wrote on 14 Sep 09:14 +0200
Re: [PATCH RFC] DRAFT doc: Add “Deprecation Pol icy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
87ed5m7lma.fsf@gnu.org
Ludovic Courtès writes:

Hi!

Toggle quote (9 lines)
> I realize I did not advertise the “Deprecation Policy” proposal here,
> which is a mistake because it’s relevant to all of us as developers and
> packagers, and it’s also a key element of our relation with the broader
> user base.
>
> So please, consider reading the proposal and joining the discussion:
>
> https://issues.guix.gnu.org/72840

Thanks, looks good to me! As a side remark: It would be nice if
upgrading of config.scm / home.scm could be automated.

Anyway, I do have a vaguely related question. The Dezyne package comes
with a `guix.scm' that uses a package description in
guix/pack/dezyne.scm, which uses `%gnu-build-system-modules'.

Recently, %gnu-build-system-modules was deprecated in

Toggle snippet (7 lines)
28dbfdb38f52f5814fb4cba9c02831d2ab0dc079
build-system/gnu: Introduce ‘%gnu-build-system-modules’ deprecated alias.

9e4ce281dbd92e3c52b831824ebb1f77023c960c
build-systems: gnu: Export %default-gnu-imported-modules and %default-gnu-modules.

Although the `guix.scm' has a comment like

Toggle snippet (5 lines)
;; To use the canonical commit that has everything prebuilt:
;;
;; guix time-machine --commit=918b7d102c2051c3d6c6ba54c8d265affec5282c -- shell

documenting a commit that can be used for building the package and has
substitutes available, usage of the commit is not enforced. After a
recent `guix pull', we now get this warning

Toggle snippet (3 lines)
pack/dezyne.scm:69:20: warning: '%gnu-build-system-modules' is deprecated, use '%default-gnu-imported-modules' instead

and I'm wondering what the best moment would be to change the package
description. Upgrading sooner (i.e., now) means that a future guix that
has this deprecated feature removed will be able to build more
hystorical releases of the package simply by doing `guix shell', so
that's probably the best choice? It would mean that all developers have
to upgrade now (or use the time machine).

Of course, we can always(?) build hystorical release by doing

$(grep -o 'guix time.*' guix.scm)

but you'd have to know about that and it probably only works for the
Dezyne package. Is there a better way or should something like this be
advertised/recommended in the documentation?

Greetings
Janneke

--
Janneke Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond https://LilyPond.org
Freelance IT https://www.JoyOfSource.com| Avatar® https://AvatarAcademy.com
K
K
Konrad Hinsen wrote on 15 Sep 10:22 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 72840@debbugs.gnu.org)
m1frq11g42.fsf@fastmail.net
Hi Ludo,

Toggle quote (9 lines)
>> There's also a use case missing in the list in the beginning: Guix as a
>> dependency of some other software, which in the worst case is no longer
>> ...

> I think this is covered by the last point:
>
> +development of external tools that use programming interfaces such as
> +the @code{(guix ...)} modules.

Yes and no. I see external tools as two distinct use cases:

- their development
- their application

The missing case is application.

Toggle quote (3 lines)
> There are quite a few actually: the CI/QA tools, package browsers like
> hpcguix-web, the Guix Workflow Language, Guix-Jupyter, rde, etc.

All those are add-on tools to the Guix CLI. I doubt these tools have any
user who wouldn't also use the Guix CLI. Meaning that they have a good
chance to learn about deprecations.

I am aware of a single tool that depends on Guix but whose functionality
is unrelated to Guix and could be implemented otherwise:


It's a Guile script that uses Guix as a library for accessing Software
Heritage. And it's a mere proof-of-concept implementation. I don't
advertise it for general use. But I do expect more such tools to appear
over time, including some with more substantial dependence on Guix.

Toggle quote (7 lines)
> As drafted here, there’s no enforcement and nobody having the duty of
> looking for violations and taking action.
>
> I view it as binding though. If a user complains that their favorite
> package as been removed in violation of the policy, then we as a
> community should review the claim and reinstate the package, unless it

OK, that sounds good enough!

Cheers,
Konrad.
A
A
Andreas Enge wrote on 16 Sep 15:43 +0200
Re: Input welcome on the proposed deprecation policy
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 72840@debbugs.gnu.org)
Zug2F6-TX5Fkgs-G@jurong
Hello,

I think we should not only remove packages that are unmaintained upstream,
but also packages that do not build.

Concretely I am thinking of a number of related packages that we have in a
version of 2019, and which has had releases since then. The project does
not build any more, just upgrading the source is not enough, and the package
definition is very complex. I have called out for help, but not received
any reply.

While I might be able to update the project, it feels like a waste of time,
since apparently no Guix user is interested in it right now.

A one-month notice period sounds appropriate to me for this.

So maybe replace:
Packages that their upstream developers have declared as having reached
``end of life'' or being unmaintained may be removed.
by
Packages that their upstream developers have declared as having reached
``end of life'' or being unmaintained, or that do not build in Guix,
may be removed.

This may be a bit brutal (I would normally argue that one should try an
update first); but if during one month nobody steps in to carry out the
update, that is telling.

Andreas
K
K
Konrad Hinsen wrote on 17 Sep 14:21 +0200
Orphaned packages
(address . 72840@debbugs.gnu.org)
m1r09izd1g.fsf@fastmail.net
Hi Andreas (et al.),

Debian has the status of "orphaned" packages for the situations that you
describe. Maybe Guix should have that as well? The main interest I see
is keeping a list of "software we had but can't handle any more",
ideally with a pointer to the last working state in Guix, e.g. the last
commit for which CI could build the package. I'd even like such packages
to show up in answers to "guix search", so that I know the difference
between "not packaged yet" and "tough case we gave up on".

Toggle quote (3 lines)
> if during one month nobody steps in to carry out the update, that is
> telling.

I don't know on which time scales other Guix users live, but for me, one
month is the average delay between two "guix pull". In other words, one
month is my notion of "immediately" when it comes to Guix.

Cheers,
Konrad.
L
L
Ludovic Courtès wrote on 23 Sep 23:44 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . indieterminacy)(address . indieterminacy@libre.brussels)(address . 72840@debbugs.gnu.org)
87msjyyrhi.fsf_-_@gnu.org
Hey there!

indieterminacy <indieterminacy@libre.brussels> skribis:

Toggle quote (7 lines)
> It may be that Im lacking a little experience,
> but Id assume that the categories outlined earlier probably require
> different timeframes:
> https://issues.guix.gnu.org/72840#0-lineno49
>
> A year feels a little arbitrary.

It’s necessarily arbitrary, but I think we have to set expectations for
users and provide guidelines for contributors; we can’t just say
“eventually”.

[...]

Toggle quote (14 lines)
> Am I the only one who feels undermined and demotivated by information
> which hits me over the head with WARNINGS?
>
> Ive had this using elogin-service (cited before):
> https://issues.guix.gnu.org/72840#0-lineno155
>
> Perhaps additionally there need to be pointers to real VCS repos,
> pinpointing a commit providing the migration inside a living
> repo/infrastructure?
>
> Such examples would be constructively showing how the change is
> achievable,
> and could be empowering through assurance and learning.

I agree. I mean, those warnings could be accompanied with a diff
showing how to change the source (GCC does that these days in some
cases), and/or it could point to examples in the manual.

This is something we should consider, but I think it shouldn’t block
a first version of the policy.

Thanks,
Ludo’.
L
L
Ludovic Courtès wrote on 23 Sep 23:47 +0200
(name . Konrad Hinsen)(address . konrad.hinsen@fastmail.net)(address . 72840@debbugs.gnu.org)
87frpqyrdv.fsf_-_@gnu.org
Hi,

Konrad Hinsen <konrad.hinsen@fastmail.net> skribis:

Toggle quote (8 lines)
> Debian has the status of "orphaned" packages for the situations that you
> describe. Maybe Guix should have that as well? The main interest I see
> is keeping a list of "software we had but can't handle any more",
> ideally with a pointer to the last working state in Guix, e.g. the last
> commit for which CI could build the package. I'd even like such packages
> to show up in answers to "guix search", so that I know the difference
> between "not packaged yet" and "tough case we gave up on".

Sounds like a good idea. This could be achieved with a package
property, maybe.

I’d like this to not block version 1 of the policy though.

Toggle quote (7 lines)
>> if during one month nobody steps in to carry out the update, that is
>> telling.
>
> I don't know on which time scales other Guix users live, but for me, one
> month is the average delay between two "guix pull". In other words, one
> month is my notion of "immediately" when it comes to Guix.

Agreed.

Ludo’.
L
L
Ludovic Courtès wrote on 24 Sep 00:11 +0200
[PATCH RFC v4] doc: Add “Deprecation Poli cy” section.
(address . 72840@debbugs.gnu.org)
7b092101ad70b100c147b7dacb6efc3393f6cb06.1727129087.git.ludo@gnu.org
* doc/contributing.texi (Deprecation Policy): New node.
(Commit Access): Link to ‘package-removal-policy’.

Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee
---
doc/contributing.texi | 199 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 196 insertions(+), 3 deletions(-)

Changes since v3:

• Mention “development *or use* of external tools” (Konrad) in the
list of use cases.

• Mark upgrade as potentially equivalent to removal (Noé, Konrad).

• Mark packages “failing to build for two months or more” as candidates
for removal (Andreas). That makes it a total of at least 3 months
before removal.

The last point is probably the most contentious.

Anything else?

Ludo’.

Toggle diff (228 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73f7addbef..d6a684306c 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -34,6 +34,7 @@ Contributing
* Commit Access:: Pushing to the official repository.
* Reviewing the Work of Others:: Some guidelines for sharing reviews.
* Updating the Guix Package:: Updating the Guix package definition.
+* Deprecation Policy:: Commitments and tools for deprecation.
* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -2805,9 +2806,11 @@ Commit Access
repository, especially for the @code{master} branch.
If you're committing and pushing your own changes, try and wait at least
-one week (two weeks for more significant changes) after you send them
-for review. After this, if no one else is available to review them and
-if you're confident about the changes, it's OK to commit.
+one week (two weeks for more significant changes, up to one month for
+changes such as removing a package---@pxref{package-removal-policy,
+Package Removal}) after you send them for review. After this, if no one
+else is available to review them and if you're confident about the
+changes, it's OK to commit.
When pushing a commit on behalf of somebody else, please add a
@code{Signed-off-by} line at the end of the commit log message---e.g.,
@@ -3030,6 +3033,196 @@ Updating the Guix Package
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@node Deprecation Policy
+@section Deprecation Policy
+
+@cindex deprecation policy
+As any lively project with a broad scope, Guix changes all the time and
+at all levels. Because it's user-extensible and programmable,
+incompatible changes can directly impact users and make their life
+harder. It is thus important to reduce user-visible incompatible
+changes to a minimum and, when such changes are deemed necessary, to
+clearly communicate them through a @dfn{deprecation period} so everyone
+can adapt with minimum hassle. This section defines the project's
+commitments for smooth deprecation and describes procedures and
+mechanisms to honor them.
+
+There are several ways to use Guix; how to handle deprecation will
+depend on each use case. Those can be roughly categorized like this:
+
+@itemize
+@item
+package management exclusively through the command line;
+
+@item
+advanced package management using the manifest and package interfaces;
+
+@item
+Home and System management, using the @code{operating-system} and/or
+@code{home-environment} interfaces together with the service interfaces;
+
+@item
+development or use of external tools that use programming interfaces
+such as the @code{(guix ...)} modules.
+@end itemize
+
+These use cases form a spectrum with varying degrees of coupling---from
+``distant'' to tightly coupled. Based on this insight, we define the
+following @dfn{deprecation policies} that we consider suitable for each
+of these levels.
+
+@table @asis
+@item Command-line tools
+Guix sub-commands should be thought of as remaining available
+``forever''. Once a Guix sub-command is to be removed, it should be
+deprecated first, and then remain available for @b{at least one year}
+after the first release that deprecated it.
+
+Deprecation should first be announced in the manual and as an entry in
+@file{etc/news.scm}; additional communication such as a blog post
+explaining the rationale is welcome. Months before the scheduled
+removal date, the command should print a warning explaining how to
+migrate. An example of this is the replacement of @command{guix
+environment} by @command{guix shell}, started in October
+2021@footnote{For more details on the @command{guix shell} transition,
+see
+@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
+
+Because of the broad impact of such a change, we recommend conducting a
+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
+@code{kubo} following a decision made upstream; to communicate the name
+change to users, the package module provided this definition:
+
+@findex deprecated-package
+@lisp
+(define-public go-ipfs
+ (deprecated-package "go-ipfs" kubo))
+@end lisp
+
+That way, someone running @command{guix install go-ipfs} or similar sees
+a deprecation warning mentioning the new name.
+
+@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{deprecated-package}
+procedure mentioned above can be used.
+
+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).
+
+If it 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.
+
+@cindex service deprecation
+@item Services
+Changes to services for Guix Home and Guix System have a direct impact
+on user configuration. For a user, adjusting to interface changes is
+rarely rewarding, which is why any such change must be clearly
+communicated in advance through deprecation warnings and documentation.
+
+Renaming of variables related to service, home, or system configuration
+must be communicated for at least six months before removal using the
+@code{(guix deprecation)} mechanisms. For example, renaming of
+@code{murmur-configuration} to @code{mumble-server-configuration} was
+communicated through a series of definitions like this one:
+
+@findex define-deprecated/public-alias
+@lisp
+(define-deprecated/public-alias
+ murmur-configuration
+ mumble-server-configuration)
+@end lisp
+
+Procedures slated for removal may be defined like this:
+
+@findex define-deprecated
+@lisp
+(define-deprecated (elogind-service #:key (config (elogind-configuration)))
+ elogind-service-type
+ (service elogind-service-type config))
+@end lisp
+
+Record fields, notably fields of service configuration records, must
+follow a similar deprecation period. This is usually achieved through
+@i{ad hoc} means though. For example, the @code{hosts-file} field of
+@code{operating-system} was deprecated by adding a @code{sanitized}
+property that would emit a warning:
+
+@lisp
+(define-record-type* <operating-system>
+ ;; @dots{}
+ (hosts-file %operating-system-hosts-file ;deprecated
+ (default #f)
+ (sanitize warn-hosts-file-field-deprecation)))
+
+(define-deprecated (operating-system-hosts-file os)
+ hosts-service-type
+ (%operating-system-hosts-file os))
+@end lisp
+
+When deprecating interfaces in @code{operating-system},
+@code{home-environment}, @code{(gnu services)}, or any popular service,
+the deprecation must come with an entry in @code{etc/news.scm}.
+
+@cindex deprecation of programming interfaces
+@item Core interfaces
+Core programming interfaces, in particular the @code{(guix ...)}
+modules, may be relied on by a variety of external tools and channels.
+Any incompatible change must be formally deprecated with
+@code{define-deprecated}, as shown above, for @b{at least one year}
+before removal. The manual must clearly document the new interface and,
+except in obvious cases, explain how to migrate from the old one.
+
+As an example, the @code{build-expression->derivation} procedure was
+superseded by @code{gexp->derivation} and remained available as a
+deprecated symbol:
+
+@lisp
+(define-deprecated (build-expression->derivation store name exp
+ #:key @dots{})
+ gexp->derivation
+ @dots{})
+@end lisp
+
+Sometimes bindings are moved from one module to another. In those
+cases, bindings must be reexported from the original module for at least
+one year.
+@end table
+
+This section does not cover all possible situations but hopefully allows
+users to know what to expect and developers to stick to its spirit.
+Please email @email{guix-devel@@gnu.org} for any questions.
+
@cindex documentation
@node Writing Documentation
@section Writing Documentation

base-commit: 637ca78f513fac15284403c0d3af64492ea832a1
--
2.46.0
L
L
Ludovic Courtès wrote on 24 Sep 00:16 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(address . 72840@debbugs.gnu.org)
87wmj2vwvf.fsf@gnu.org
The v3 -> v4 diff for clarity:
Toggle diff (47 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index f713765357..d6a684306c 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -3062,8 +3062,8 @@ Deprecation Policy
@code{home-environment} interfaces together with the service interfaces;
@item
-development of external tools that use programming interfaces such as
-the @code{(guix ...)} modules.
+development or use of external tools that use programming interfaces
+such as the @code{(guix ...)} modules.
@end itemize
These use cases form a spectrum with varying degrees of coupling---from
@@ -3111,10 +3111,12 @@ Deprecation 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. There is no formal
-deprecation mechanism for this case, unless a replacement exists, in
-which case the @code{deprecated-package} procedure mentioned above can
-be used.
+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{deprecated-package}
+procedure mentioned above can be used.
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
@@ -3133,6 +3135,14 @@ Deprecation Policy
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.
+
@cindex service deprecation
@item Services
Changes to services for Guix Home and Guix System have a direct impact
K
K
Konrad Hinsen wrote on 24 Sep 07:21 +0200
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 72840@debbugs.gnu.org)
m1frppy6c6.fsf@fastmail.net
Hi Ludo,

Toggle quote (5 lines)
> Sounds like a good idea. This could be achieved with a package
> property, maybe.
>
> I’d like this to not block version 1 of the policy though.

Certainly not!

That said, a convention for commit messages related to the cases
described in the deprecation policy would be a good start. Not just
"deprecated" or "removed", but also a keyword stating the reason.

Cheers,
Konrad.
G
G
Greg Hogan wrote on 24 Sep 18:32 +0200
Re: [bug#72840] [PATCH RFC v4] doc: Add “Deprecati on Policy” section.
(name . Ludovic Courtès)(address . ludo@gnu.org)
CA+3U0ZkKOfj-WwjJnecB4Ue7R=_w0d08zFaX8SMHsfofQt7uzA@mail.gmail.com
On Mon, Sep 23, 2024 at 6:11?PM Ludovic Courtès <ludo@gnu.org> wrote:
Toggle quote (27 lines)
>
> +@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{deprecated-package}
> +procedure mentioned above can be used.
> +
> +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).
> +
> +If it 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}.

Hi Ludo',

Is the intent for the news entry to pre-announce the removal of a
popular package, as specified for other kinds of deprecation and
removal? Otherwise, even though we have extended the review period, we
are expecting users to track the mailing lists.

Greg
A
A
Andreas Enge wrote on 25 Sep 10:47 +0200
Re: [bug#72840] [PATCH RFC v4] d oc: Add “Deprecation Policy” section.
(name . Greg Hogan)(address . code@greghogan.com)
ZvPOJGu8SJ1MBtOW@jurong
Am Tue, Sep 24, 2024 at 12:32:53PM -0400 schrieb Greg Hogan:
Toggle quote (5 lines)
> Is the intent for the news entry to pre-announce the removal of a
> popular package, as specified for other kinds of deprecation and
> removal? Otherwise, even though we have extended the review period, we
> are expecting users to track the mailing lists.

No, I think the idea is to do it after the removal, but so that "guix pull"
prints a message. Then users can adapt.

Andreas
L
L
Ludovic Courtès wrote on 26 Sep 15:16 +0200
Re: [PATCH RFC] DRAFT doc: Add “Deprecation Pol icy” section.
(name . Janneke Nieuwenhuizen)(address . janneke@gnu.org)
87ldzeo8qd.fsf@gnu.org
Hi Janneke,

Janneke Nieuwenhuizen <janneke@gnu.org> skribis:

Toggle quote (5 lines)
>
> Thanks, looks good to me! As a side remark: It would be nice if
> upgrading of config.scm / home.scm could be automated.

It would be great, indeed.

Toggle quote (12 lines)
> Anyway, I do have a vaguely related question. The Dezyne package comes
> with a `guix.scm' that uses a package description in
> guix/pack/dezyne.scm, which uses `%gnu-build-system-modules'.
>
> Recently, %gnu-build-system-modules was deprecated in
>
> 28dbfdb38f52f5814fb4cba9c02831d2ab0dc079
> build-system/gnu: Introduce ‘%gnu-build-system-modules’ deprecated alias.
>
> 9e4ce281dbd92e3c52b831824ebb1f77023c960c
> build-systems: gnu: Export %default-gnu-imported-modules and %default-gnu-modules.

I’m not convinced this was a worthwhile change BTW, looking at the
intended clarity improvement vs. cost ratio.

Toggle quote (20 lines)
> Although the `guix.scm' has a comment like
>
> ;; To use the canonical commit that has everything prebuilt:
> ;;
> ;; guix time-machine --commit=918b7d102c2051c3d6c6ba54c8d265affec5282c -- shell
>
>
> documenting a commit that can be used for building the package and has
> substitutes available, usage of the commit is not enforced. After a
> recent `guix pull', we now get this warning
>
> pack/dezyne.scm:69:20: warning: '%gnu-build-system-modules' is deprecated, use '%default-gnu-imported-modules' instead
>
> and I'm wondering what the best moment would be to change the package
> description. Upgrading sooner (i.e., now) means that a future guix that
> has this deprecated feature removed will be able to build more
> hystorical releases of the package simply by doing `guix shell', so
> that's probably the best choice? It would mean that all developers have
> to upgrade now (or use the time machine).

Yeah, that’s always a difficult choice, and I don’t have a good answer.
What’s sure is that the deprecated name will remain available for a
relatively long time, so there’s no urgency at this point.

Toggle quote (4 lines)
> but you'd have to know about that and it probably only works for the
> Dezyne package. Is there a better way or should something like this be
> advertised/recommended in the documentation?

I’m not sure we could recommend one approach that would work for
everyone because it really depends on the use case (for instance whether
building with an older Guix is important for your project. But at
least, by setting expectations, the deprecation policy lets users making
informed decisions.

Ludo’.
L
L
Ludovic Courtès wrote on 2 Oct 18:20 +0200
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Depr ecation Policy” section.
(name . Greg Hogan)(address . code@greghogan.com)
87y136v5mr.fsf_-_@gnu.org
Greg Hogan <code@greghogan.com> skribis:

Toggle quote (2 lines)
> On Mon, Sep 23, 2024 at 6:11?PM Ludovic Courtès <ludo@gnu.org> wrote:

[...]

Toggle quote (18 lines)
>> +If it 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}.
>
> Hi Ludo',
>
> Is the intent for the news entry to pre-announce the removal of a
> popular package, as specified for other kinds of deprecation and
> removal?

What the paragraph above means is that a news entry is published when
the popular package is deprecated, which could be months before it is
removed.

Does that make sense?

Ludo’.
L
L
Ludovic Courtès wrote on 12 Oct 19:54 +0200
(address . 72840-done@debbugs.gnu.org)
87wmidqk9b.fsf_-_@gnu.org
Hello,

Ludovic Courtès <ludo@gnu.org> skribis:

Toggle quote (5 lines)
> * doc/contributing.texi (Deprecation Policy): New node.
> (Commit Access): Link to ‘package-removal-policy’.
>
> Change-Id: I5d095559920a3d9b791b5d919aab4e2f2a0c2dee

The discussion had dried up so I pushed this version (v4) as commit
9d1b97d7a4ab9c0dbd5808e7859d52cff338f377.

Let’s not consider it set in stone though: if there are suggestions to
improve this section, please go ahead, but bear in mind that time is
needed so everyone interested gets a chance to participate.

(As Simon noted, documenting an RFC process will help us clarify that.)

Ludo’.
Closed
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send an email to 72840@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 72840
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch