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

[Daniel Mendler]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  66554@debbugs.gnu.org,
>>   monnier@iro.umontreal.ca,  stefankangas@gmail.com
>> Date: Thu, 18 Jan 2024 19:51:27 +0000
>> 
>> Pinging this thread with an updated version of the patch:
>
> 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.

As of now, the Compat manual already mentions the arrangement with the
compat.el file in core as a possible future development, but does not
expand on it in detail. This part of the manual will be updated and
greatly expanded.

>> +** 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"?

Daniel