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

["Ludovic Courtès" <ludo@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 32 bytes --]

The v3 -> v4 diff for clarity:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 2024 bytes --]

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f713765357..d6a684306c 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -3062,8 +3062,8 @@ Deprecation Policy
 @code{home-environment} interfaces together with the service interfaces;
 
 @item
-development of external tools that use programming interfaces such as
-the @code{(guix ...)} modules.
+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
@@ -3111,10 +3111,12 @@ Deprecation 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.
+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
@@ -3133,6 +3135,14 @@ Deprecation Policy
 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