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

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

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