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

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

[Ludovic Courtès]

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’.

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

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

[pelzflorian (Florian Pelz)]

Hello Ludo.  Having a deprecation policy clarifies things.  Thank you
for writing a good one!

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

typo: 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 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.)


> […]
> +@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

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

[Ludovic Courtès]

Hi Florian,

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

> Hello Ludo.  Having a deprecation policy clarifies things.  Thank you
> for writing a good one!

Thanks for taking a look!

>> +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).

> 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.

>> […]
>> +@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.

[...]

> 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:

> 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’.

[bug#72840] [PATCH RFC v2] doc: Add “Deprecation Policy” section.

[Ludovic Courtès]

* 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
+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

[bug#72840] [PATCH RFC v2] doc: Add “Deprecation Policy” section.

[Maxim Cournoyer]

Hi Ludovic,

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

> * 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
                                                    
> +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.

> +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/

> +``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

[bug#72840] [PATCH RFC v3] doc: Add “Deprecation Policy” section.

[Ludovic Courtès]

* 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.

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

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

[Ludovic Courtès]

Hello,

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

> 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.

> 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’.

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

[Noé Lopez via Guix-patches via]

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.

>+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.

[bug#72840] Deprecation policy

[Konrad Hinsen]

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
(https://hpc.guix.info/events/2023/workshop/program/#caring-for-your-environment-s-)

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.

[bug#72840] [PATCH RFC v3] doc: Add “Deprecation Policy” section.

[Maxim Cournoyer]

Hi,

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

> * 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

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

[Greg Hogan]

On Wed, Sep 11, 2024 at 2:33 PM Noé Lopez via Guix-patches via
<guix-patches@gnu.org> wrote:
>
> – 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.

> >+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

[bug#72839] Using RFC process? (was Re: [bug#72839] [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.)

[Simon Tournier]

Hey!

Cool but…

On Tue, 27 Aug 2024 at 21:13, Ludovic Courtès <ludo@gnu.org> wrote:

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

…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?

BTW, that’s the typical subject for a RFC [1], IMHO. :-)

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

Cheers,
simon

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

[Ludovic Courtès]

Hi,

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

> – 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.

> – 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?

>>+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’.

> 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’.

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

[Ludovic Courtès]

Hi Konrad,

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

> 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.

> 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.

[...]

> 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’.

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

[Ludovic Courtès]

Hi Simon,

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

> …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.

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

Sure.

> 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’.

[bug#72839] bug#72840: [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.

[Simon Tournier]

Hi Ludo,

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

> 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.

> 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

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

[indieterminacy]

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.

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):
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.

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

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

[Konrad Hinsen]

Hi Ludo,

>> 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.

> 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:

  https://github.com/khinsen/swh-checkout

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.

> 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.

[bug#72840] Orphaned packages

[Konrad Hinsen]

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".

> 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.

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

[Ludovic Courtès]

Hey there!

indieterminacy <indieterminacy@libre.brussels> skribis:

> 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”.

[...]

> 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’.

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

[Ludovic Courtès]

Hi,

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

> 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.

>> 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’.

[bug#72840] [PATCH RFC v4] doc: Add “Deprecation Policy” section.

[Ludovic Courtès]

* 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’.

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

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

[Konrad Hinsen]

Hi Ludo,

> 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.

[bug#72840] [PATCH RFC v4] doc: Add “Deprecation Policy” section.

[Greg Hogan]

On Mon, Sep 23, 2024 at 6:11 PM Ludovic Courtès <ludo@gnu.org> wrote:
>
> +@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

[bug#72840] [PATCH RFC v4] doc: Add “Deprecation Policy” section.

[Andreas Enge]

Am Tue, Sep 24, 2024 at 12:32:53PM -0400 schrieb Greg Hogan:
> 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

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

[Ludovic Courtès]

Greg Hogan <code@greghogan.com> skribis:

> On Mon, Sep 23, 2024 at 6:11 PM Ludovic Courtès <ludo@gnu.org> wrote:

[...]

>> +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’.

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

[Ludovic Courtès]

Hello,

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

> * 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’.