--- Begin Message ---
Subject: |
[PATCH RFC] DRAFT doc: Add “Deprecation Policy” section. |
Date: |
Tue, 27 Aug 2024 21:30:35 +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@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
--- End Message ---
--- Begin Message ---
Subject: |
Re: bug#72840: [PATCH RFC] DRAFT doc: Add “Deprecation Policy” section. |
Date: |
Thu, 05 Sep 2024 23:26:25 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
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’.
--- End Message ---