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