Re: Improving documentation of Org Mode integration into Emacs.

[Karl Fogel <kfogel@red-bean.com>]

[-- Attachment #1: Type: text/plain, Size: 2430 bytes --]

On 05 Jan 2022, Eli Zaretskii wrote:
>I think we should explain the issue concisely, and then provide
>specific 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/, 
>and
>only 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 
>with
>precise 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 
>found
>out 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 
>will
>also 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: [PATCH] Document external maintenance of some packages --]
[-- Type: text/x-diff, Size: 4022 bytes --]

From 6a9a0132b7313a16539b2ec8b3fb9cac390b5915 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Sun, 9 Jan 2022 16:07:08 -0600
Subject: [PATCH] Document external maintenance of some packages

Document the fact that some packages in Emacs are externally
maintained, and specifically document Org Mode's external maintenance.

For more context, see the thread that starts here:

  https://lists.gnu.org/archive/html/emacs-devel/2021-12/msg00366.html
  From: Karl Fogel
  To: Emacs Devel
  Subject: Improving documentation of Org Mode integration into Emacs.
  Date: Sat, 04 Dec 2021 15:14:59 -0600
  Message-ID: <87zgpgax7w.fsf@red-bean.com>
---
 CONTRIBUTE        | 18 ++++++++++++++++++
 admin/MAINTAINERS | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git CONTRIBUTE CONTRIBUTE
index 7c3421ed75..04d0ab00d2 100644
--- CONTRIBUTE
+++ CONTRIBUTE
@@ -366,6 +366,24 @@ reasons.  These should be marked by including something like "Do not
 merge to master" or anything that matches gitmerge-skip-regexp (see
 admin/gitmerge.el) in the commit message.
 
+** Some packages in Emacs are maintained externally
+
+Sometimes a package that ships as part of GNU Emacs is maintained as a
+separate project, with its own upstream repository, its own maintainer
+group, its own development conventions, etc.  The upstream project's
+code is periodically merged into Emacs (exactly when and how such
+merges happen depends on the package).
+
+So when you are making a contribution -- such as fixing a bug or
+proposing an enhancement -- to one of these externally maintained
+packages, you often need to deal with that package at its upstream
+source.
+
+See section "Externally maintained packages" in "admin/MAINTAINERS"
+for a list of such packages.  If you discover an externally maintained
+package in Emacs that is not yet listed there, please send in a patch
+or just let us know.
+
 ** GNU ELPA
 
 This repository does not contain the Emacs Lisp package archive
diff --git admin/MAINTAINERS admin/MAINTAINERS
index e87c3e0204..5b8d73cad7 100644
--- admin/MAINTAINERS
+++ admin/MAINTAINERS
@@ -316,6 +316,43 @@ Modus themes
         doc/misc/modus-themes.org
         etc/themes/modus*.el
 
+Org Mode
+	Home Page: https://orgmode.org/
+	Maintainer: Org Mode developers
+	Repository: git://git.sv.gnu.org/emacs/org-mode.git
+	Mailing list: emacs-orgmode@gnu.org
+	Bug Reports: M-x org-submit-bug-report
+	Notes: Org Mode is maintained as a separate project that is
+          periodically merged into Emacs.  To view or participate in
+          Org Mode development, please go to https://orgmode.org/ and
+          follow the instructions there.
+
+          The source code from the upstream Org Mode project is
+          usually not identical to the version of Org Mode in Emacs.
+          The upstream project often has recent changes that have not
+          yet been merged into Emacs, and Emacs sometimes has local
+          changes to Org Mode that have not yet been backported to
+          upstream.  https://orgmode.org/worg/org-maintenance.html
+          documents how the Org Mode project synchronizes changes with
+          Emacs.
+
+          If you're investigating a bug you encountered in Org Mode in
+          Emacs, you should obtain the latest upstream code and see if
+          the bug is present there.  If the bug is present, then the
+          upstream Org Mode project is the proper place to fix it.  If
+          the bug is not present there, that could be because it has
+          already been fixed upstream, or it could be because the bug
+          was only introduced on the Emacs side and has not yet been
+          backported upstream.  You will need to figure out what the
+          situation is in order to know where to contribute your fix.
+
+	lisp/org/*.el
+	etc/org/*
+	etc/refcards/orgcard.tex
+	doc/misc/org.org
+	doc/misc/org-setup.org
+	doc/misc/org.texi
+
 \f
 ;;; Local Variables:
 ;;;   coding: utf-8
-- 
2.34.1