Subject: bug#66554: [PATCH] Add the public API of Compat to the core

From: Daniel Mendler <[email-masked]>
Date: Fri, 19 Jan 2024 07:57:51 +0100

Eli Zaretskii <[email-masked]> writes:

>> From: Daniel Mendler <[email-masked]>
>> Cc: Philip Kaludercic <[email-masked]>,  [email-masked],
>>   [email-masked],  [email-masked]
>> Date: Thu, 18 Jan 2024 21:35:59 +0100
>> 
>> Eli Zaretskii <[email-masked]> writes:
>> 
>> > I find the documentation of this arrangement still insufficient.  The
>> > way this stuff works (which required Daniel to write 150 lines of
>> > explanation) is mostly kept out of the written docs, so we'll have to
>> > rely on people's memory.  Can we document this machinery better?
>> 
>> I agree. Where do you suggest to add the documentation? My intention is
>> to update the Compat manual (of the Compat ELPA package) with a more
>> detailed explanation of the mechanism as soon as the compat.el file gets
>> added to the Emacs core. We may want to avoid to duplicate the
>> information, by keeping the documentation in the Emacs compat.el file
>> concise, referring mainly to the Compat manual.
>
> The Compat manual cannot be the only place, because the information
> I'm talking about should be aimed at the Emacs developers, so it must
> be part of Emacs.  I suggest to have it in the commentary in
> compat.el.

Okay, let's add the information to the commentary. Then we also copy the
information to the Compat manual, to a section where we describe how the
versioning works.

>> >> +** New package Compat
>> >> +The Compat package on GNU ELPA provides forwards-compatibility
>> >> +support, so that packages that still provide support for older
>> >
>> > I think this is known as "backward compatibility".
>> 
>> Compat allows packages to use APIs which are newer than the Emacs they
>> depend on. A package depending on ((emacs "27.1") (compat "29.1"))
>> relies on Emacs 27.1 as base line, but can use some APIs from 29.1,
>> specifically the ones provided by Compat. Is there a better and more
>> specific term for this than "forward compatibility"?
>
> How about
>
>   Compat allows packages written for newer Emacs version to still work
>   with older Emacs versions.

I think this formulation gets it backwards. See my other mail regarding
backward- vs forwards-compatibility. One could also write:

   Compat allows packages written for older Emacs versions to use
   features introduced in newer Emacs versions.

Daniel