GNU bug report logs - #66554
[PATCH] Add the public API of Compat to the core

Previous Next

Full log

View this message in rfc822 format

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66554 <at> debbugs.gnu.org, philipk <at> posteo.net, monnier <at> iro.umontreal.ca, stefankangas <at> gmail.com
Subject: bug#66554: [PATCH] Add the public API of Compat to the core
Date: Fri, 19 Jan 2024 07:57:51 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: Philip Kaludercic <philipk <at> posteo.net>,  66554 <at> debbugs.gnu.org,
>>   monnier <at> iro.umontreal.ca,  stefankangas <at> gmail.com
>> Date: Thu, 18 Jan 2024 21:35:59 +0100
>> 
>> Eli Zaretskii <eliz <at> gnu.org> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.