doc: Recommend ‘define-deprecated-package’ in the Deprecation Policy.

* doc/contributing.texi (Deprecation Policy): Document and recommend
‘define-deprecated-package’.

Change-Id: I530310f5216f09025525d91f690bb3885fe2cfb4

1 files changed, 13 insertions, 5 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 6c4423a6900..d1e2e63758b 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -3344,13 +3344,21 @@ for @b{at least one year}.  For example, @code{go-ipfs} was renamed to
 change to users, the package module provided this definition:
 
 @findex deprecated-package
+@findex define-deprecated-package
 @lisp
-(define-public go-ipfs
-  (deprecated-package "go-ipfs" kubo))
+(define-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.
+a deprecation warning mentioning the new package name; likewise, someone
+referring to the @code{go-ipfs} @emph{variable} from their manifest or
+package definition will see a warning.
+
+Under the hood, @code{define-deprecated-package} combines
+@code{define-deprecated/public-alias} to mark the variable as deprecated
+(see below), and the @code{deprecated-package} procedure to mark the
+package name as deprecated.
 
 @cindex package removal policy
 @anchor{package-removal-policy}
@@ -3360,8 +3368,8 @@ 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.
+replacement exists, in which case the @code{define-deprecated-package}
+macro 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