|
From: | Karl Fogel |
Subject: | Re: Improving documentation of Org Mode integration into Emacs. |
Date: | Sun, 09 Jan 2022 16:34:16 -0600 |
User-agent: | Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) |
On 05 Jan 2022, Eli Zaretskii wrote:
I think we should explain the issue concisely, and then providespecific instructions. This text is IMO enough for the first part:[...]Following that, we should provide a full, exhaustive list of all such packages in Emacs core, each one with a corresponding URL (mailing list, upstream repository with an issue tracker, etc.). It might be a good idea to have this list on a separate file, perhaps in etc/, andonly have CONTRIBUTE point to that file.
The attached patch puts a concise text in CONTRIBUTE as you described, and adds an entry for Org Mode to the new "Externally maintained packages" section of admin/MAINTAINERS -- following Michael Albinius's and Protesilaos Stavrou's lead re Tramp and Modus Themes respectively.
The Org Mode entry is larger than the Tramp and Modus Themes entries, because the situation with Org Mode is more complex. That's why I've attached this patch for review instead of just committing it.
I disagree. If we don't provide a full list of such packages withprecise instructions, we will not make any significant progress:people would still need to ask us about the details, when they aren't "smart" enough (or patient enough) to read the instructions that teach them how to deduce that by themselves. Moreover, as you have foundout already, there's no standard way such packages use to "plug"themselves into Emacs, so it's likely that any general instructions we provide will be inaccurate in some cases. An exhaustive "cookbook" is much better, IMO, and is easier to maintain in the long run. It willalso be shorter, which is a nice bonus, given today's "TL;DR" attitude.
That's persuasive; I think it's a good solution. Feedback on the attached patch is welcome. A couple of notes about it:
* Although the "Branches" section in CONTRIBUTE implies that these changes should go on the "emacs-28" branch, this patch is against "master" because Michael and Protesilaos committed their changes to "master". (I think it's all fine on "master" too, and the guidance in CONTRIBUTE is a bit ambiguous about this kind of change anyway.)
* In admin/MAINTAINERS, I did not list "test/lisp/org/org-tests.el" as a file maintained by the Org Mode project, because it looks like that file exists only in Emacs and is not shipped with Org Mode.
Best regards, -Karl
0001-Document-external-maintenance-of-some-packages.patch
Description: [PATCH] Document external maintenance of some packages
[Prev in Thread] | Current Thread | [Next in Thread] |