From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Daniel Mendler via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#66554: [PATCH] Add the public API of Compat to the core Date: Fri, 26 Jan 2024 11:42:30 +0100 Message-ID: <87a5osfka1.fsf@daniel-mendler.de> References: <87pm1ggrdx.fsf@posteo.net> <87bk9raaad.fsf@daniel-mendler.de> <87a5pbvbxc.fsf@posteo.net> <875xzza8jw.fsf@daniel-mendler.de> <87edemldlw.fsf@posteo.net> <83cyu6ifzw.fsf@gnu.org> <875xzyl8lq.fsf@posteo.net> <837ckeievw.fsf@gnu.org> <87h6jiqtsp.fsf@daniel-mendler.de> <835xzyiagj.fsf@gnu.org> <871qamkx0m.fsf@posteo.net> <83wmsdhgw8.fsf@gnu.org> <87wmsdxvz6.fsf@daniel-mendler.de> <878r4ml8sg.fsf@posteo.net> <83v87qwg48.fsf@gnu.org> <87h6jaz8eo.fsf@daniel-mendler.de> <83r0idx1p1.fsf@gnu.org> <87mst1tgrt.fsf@posteo.net> <874jf39rn7.fsf@daniel-mendler.de> <871qa47ch1.fsf@posteo.net> Reply-To: Daniel Mendler Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35635"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 66554@debbugs.gnu.org, Eli Zaretskii , stefankangas@gmail.com, monnier@iro.umontreal.ca To: Philip Kaludercic Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jan 26 11:43:07 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rTJfu-000930-Bn for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 26 Jan 2024 11:43:06 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rTJfm-0008Hp-ID; Fri, 26 Jan 2024 05:42:58 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rTJfk-0008Gg-Go for bug-gnu-emacs@gnu.org; Fri, 26 Jan 2024 05:42:56 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rTJfk-00014n-5b for bug-gnu-emacs@gnu.org; Fri, 26 Jan 2024 05:42:56 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rTJfq-0001jO-EN for bug-gnu-emacs@gnu.org; Fri, 26 Jan 2024 05:43:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Daniel Mendler Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 26 Jan 2024 10:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66554 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 66554-submit@debbugs.gnu.org id=B66554.17062657686630 (code B ref 66554); Fri, 26 Jan 2024 10:43:02 +0000 Original-Received: (at 66554) by debbugs.gnu.org; 26 Jan 2024 10:42:48 +0000 Original-Received: from localhost ([127.0.0.1]:50521 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rTJfc-0001is-4l for submit@debbugs.gnu.org; Fri, 26 Jan 2024 05:42:48 -0500 Original-Received: from server.qxqx.de ([2a01:4f8:c012:9177::1]:34143 helo=mail.qxqx.de) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rTJfY-0001iZ-MF for 66554@debbugs.gnu.org; Fri, 26 Jan 2024 05:42:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=daniel-mendler.de; s=key; h=Content-Type:MIME-Version:Message-ID:Date: References:In-Reply-To:Subject:Cc:To:From:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=bixbl4AOkA75KFd71Yek4jIGhmYvHKAgOJ7t5ZF3EeQ=; b=sV3UsBWrHd30Nh7+P3wVTMaXgs bVwsbbRePcER72AbFFrgX8SuA4HQl5/LZZiBSQBh1y5jzZ8IZHZX6mPA4bpPfY83hHLdCvtTJuIDS L6tHajhlHgoh7hJqOfaoevJ8cJgrxHFiMXPnqag9FByDRifZOrG2sxEOGvBKJHQDx2dQ=; In-Reply-To: <871qa47ch1.fsf@posteo.net> (Philip Kaludercic's message of "Fri, 26 Jan 2024 07:58:18 +0000") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:278914 Archived-At: Philip Kaludercic writes: [...] >> Philip, do you plan to submit a new version of the patch or do you want >> me to update the patch with a more extensive explanation? We should keep >> in mind that the information we add to the Emacs compat.el cannot be >> self sufficient. Emacs developers who want to use Compat must consult >> the Compat manual, since that's the place where we document the >> available compatibility definitions. Therefore referring to the manual >> for further details should be okay, as long as the general mechanism >> (and the versioning) is explained sufficiently well in the commentary of >> the compat.el file in Emacs. > > I have tried to update the patch to clarify some of the points in the > discussion, but feel free to change anything you think ought to be changed: Thank you, Philip. I added a few comments below, mostly about some details of the wording. Eli, Stefans, do you think the level of information provided in the patch is sufficient? > diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi > index 6f52a33d194..b9239521d33 100644 > --- a/doc/lispref/package.texi > +++ b/doc/lispref/package.texi [...] > +The versioning of Compat follows that of Emacs, so one can implicitly > +declare what range of Emacs versions a package supports like so: > + > +@example > +;; Package-Requires: ((emacs "27.2") (compat "29.1")) > +@end example The word "range" is misleading. It sounds as if the package supports 27.2 to 29.1, while in it actually supports 27.2 and newer and relies on some 29.1 APIs. [...] > diff --git a/etc/NEWS b/etc/NEWS > index a1874313502..46859d75aac 100644 > --- a/etc/NEWS > +++ b/etc/NEWS > @@ -1321,6 +1321,17 @@ This minor mode generates the tags table automatically based on the > current project configuration, and later updates it as you edit the > files and save the changes. > > ++++ > +** New package Compat > +The Compat package on GNU ELPA provides forwards-compatibility > +support, so that packages that still provide support for older > +versions of Emacs can still make use of newer definitions that can be > +reasonably re-implemented in Elisp. Now a "pseudo" Compat package is > +part of Emacs, that doesn't provide any compatibility support, but > +only implements the public-facing API of Compat so that core packages > +can use Compat, while also preventing the installation of Compat on > +the most recent version of Emacs. This NEWS entry explains the addition well, but it is a bit verbose compared to other entries. I am not fond of the quoted word "pseudo". Maybe say stub of Compat? > * Incompatible Lisp Changes in Emacs 30.1 > > diff --git a/lisp/emacs-lisp/compat.el b/lisp/emacs-lisp/compat.el > new file mode 100644 > index 00000000000..2882974cf2d > --- /dev/null > +++ b/lisp/emacs-lisp/compat.el > @@ -0,0 +1,94 @@ > +;;; compat.el --- Pseudo-Compatibility for Elisp -*- lexical-binding: t; -*- Instead of "Pseudo" maybe write "Stub of the Emacs Lisp Compatibility Library"? We could also use "Emacs Lisp Compatibility Library" like in ELPA Compat package, since for packages using the Compat library it should not make a difference if the builtin compat.el stub or the ELPA package is used. > +;;; Commentary: [...] > +;; Note that Compat is NOT a core package and this file is NOT > +;; available on GNU ELPA. I find this sentence a bit confusing. What you want to tell here is that the compat.el file in Emacs differs from the compat.el file in the ELPA package. This is maybe already clear from the other comments so we can as well remove this sentence? [...] > +;;;; Clever trick to avoid installing Compat if not necessary > + > +;; The versioning scheme of the Compat package follows that of Emacs, > +;; to indicate what version of Emacs is being supported. For example, ^^^^^^^^^ Should we say "supported" here? Compat supports other version than the one specified. Compat "provides" functionality from that Emacs version. > +;; the Compat version number 29.2.3.9 would attempt to provide > +;; compatibility definitions up to Emacs 29.2, while also designating > +;; that this is the third major release and ninth minor release of > +;; Compat, for the specific Emacs release. > + > +;; The package version of this file is specified programmatically, > +;; instead of giving a fixed version in the header of this file. This > +;; is done to ensure that the version of compat.el provided by Emacs > +;; is always corresponds to the current version of Emacs. In addition ^^ The "is" should be removed. > +;; to the major-minor version, a large "major release" makes sure that > +;; the built-in version of Compat is always preferred over an external > +;; installation. This means that if a package specifies a dependency > +;; on Compat which matches the current version of Emacs that is being ^^^^^^^^^^^^^^^^^^^ ...which matches the current *or an older version* of Emacs... > +;; used, no additional dependencies have to be downloaded. > +;; > +;; Further details and background on this file can be found in the > +;; bug#66554 discussion. > + > +;;;###autoload (push (list 'compat > +;;;###autoload emacs-major-version > +;;;###autoload emacs-minor-version > +;;;###autoload 1.0e+INF) > +;;;###autoload package--builtin-versions) I prefer if we use 9999 here instead of 1.0e+INF. While infinity is semantically correct, the float may lead to problems and hurt readability in the package list. > +(provide 'compat) > +;;; compat.el ends here Daniel