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

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

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