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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 72839 in the body.
You can then email your comments to 72839 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: guix-patches <at> gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.
Date: Tue, 27 Aug 2024 21:13:09 +0200

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

Message #14 received at 72839 <at> debbugs.gnu.org (full text, mbox):

From: Simon Tournier <zimon.toutoune <at> gmail.com>
To: Ludovic Courtès <ludo <at> gnu.org>, 72839 <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>,
 Florian Pelz <pelzflorian <at> pelzflorian.de>,
 Matthew Trzcinski <matt <at> excalamus.com>
Subject: Using RFC process? (was Re: [bug#72839] [PATCH RFC] DRAFT doc: Add
 “Deprecation Policy” section.)
Date: Fri, 13 Sep 2024 18:41:50 +0200

Hey!

Cool but…

On Tue, 27 Aug 2024 at 21:13, Ludovic Courtès <ludo <at> 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

Message #17 received at 72839 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Simon Tournier <zimon.toutoune <at> gmail.com>
Cc: Matthew Trzcinski <matt <at> excalamus.com>, 72839 <at> debbugs.gnu.org,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, 72840 <at> debbugs.gnu.org,
 Florian Pelz <pelzflorian <at> pelzflorian.de>
Subject: Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.
Date: Fri, 13 Sep 2024 19:38:00 +0200

Hi Simon,

Simon Tournier <zimon.toutoune <at> 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’.

Message #20 received at 72839 <at> debbugs.gnu.org (full text, mbox):

From: Simon Tournier <zimon.toutoune <at> gmail.com>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: Matthew Trzcinski <matt <at> excalamus.com>, 72839 <at> debbugs.gnu.org,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, 72840 <at> debbugs.gnu.org,
 Florian Pelz <pelzflorian <at> pelzflorian.de>
Subject: Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section.
Date: Fri, 13 Sep 2024 20:11:35 +0200

Hi Ludo,

On Fri, 13 Sept 2024 at 19:38, Ludovic Courtès <ludo <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.