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

From: Eli Zaretskii <[email-masked]>
Date: Fri, 19 Jan 2024 08:43:54 +0200

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

> >> +** 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.