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

["pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de>]

Hello Ludo.  Having a deprecation policy clarifies things.  Thank you
for writing a good one!

Ludovic Courtès <ludo@gnu.org> writes:
> +@item Package removal
> +Packages that their upstream developers have declared as having reach

typo: 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.
> +
> +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?

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.)


> […]
> +@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:

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.

Regards,
Florian