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

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

[Janneke Nieuwenhuizen]

Ludovic Courtès writes:

Hi!

> 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

--8<---------------cut here---------------start------------->8---
28dbfdb38f52f5814fb4cba9c02831d2ab0dc079
build-system/gnu: Introduce ‘%gnu-build-system-modules’ deprecated alias.

9e4ce281dbd92e3c52b831824ebb1f77023c960c
build-systems: gnu: Export %default-gnu-imported-modules and %default-gnu-modules.
--8<---------------cut here---------------end--------------->8---

Although the `guix.scm' has a comment like

--8<---------------cut here---------------start------------->8---
;; To use the canonical commit that has everything prebuilt:
;;
;;   guix time-machine --commit=918b7d102c2051c3d6c6ba54c8d265affec5282c -- shell
--8<---------------cut here---------------end--------------->8---

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

--8<---------------cut here---------------start------------->8---
pack/dezyne.scm:69:20: warning: '%gnu-build-system-modules' is deprecated, use '%default-gnu-imported-modules' instead
--8<---------------cut here---------------end--------------->8---

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

[bug#72840] Input welcome on the proposed deprecation policy

[Andreas Enge]

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

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

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

[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] [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 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#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