Re: Improving documentation of Org Mode integration into Emacs.

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

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

On 05 Dec 2021, Eli Zaretskii wrote:
>> I'd like to improve our in-tree documentation of how Org Mode 
>> integration into GNU Emacs works.
>
>Thanks.  Can you provide a rough sketch, in the form of list of 
>items,
>of what you'd like to document, and who would be the main 
>audience for
>that?  I don't have a clear idea of that based on what you 
>posted.

Sure.  (The attached patch may answer your questions more 
efficiently, though.)

* Audience:

The audience is Emacs developers and potential developers who are 
tracking down bugs, or trying to contribute enhancements, but who 
don't know that certain packages (such as Org Mode) are externally 
maintained. 

It's better for us all if such a person finds out as soon as 
possible where the active upstream for a package is.  For example, 
if they've found a bug in Org Mode, they should take the bug 
report to the Org Mode forums and discuss it with the Org Mode 
maintainers.  (Maybe sometimes Emacs Devel should also be 
involved, but the person should at least start out in the proper 
upstream forum and then be guided appropriately from there.)

* List of items:

All the packages that ship as part of Emacs but that are 
externally maintained.  Right now, Org Mode is the only one I know 
of, but I suspect there are others.  If people would like to point 
others out to me, I'll update the attached patch to include them 
too.

The attached patch is an attempt to document this situation in 
such a way that developers are likely to encounter the 
documentation when they most need it.  Comments welcome; I'm 
certainly open to other strategies.

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: 2490 bytes --]

From b709de6a9ffb4cbb30b480f97f1de009a00769a9 Mon Sep 17 00:00:00 2001
From: Karl Fogel <kfogel@red-bean.com>
Date: Sun, 2 Jan 2022 22:49:35 -0600
Subject: [PATCH] Document external maintenance of some packages

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

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      | 17 +++++++++++++++++
 lisp/org/README |  6 ++++++
 2 files changed, 23 insertions(+)
 create mode 100644 lisp/org/README

diff --git CONTRIBUTE CONTRIBUTE
index 7c3421ed75..6f3bb9bf32 100644
--- CONTRIBUTE
+++ CONTRIBUTE
@@ -366,6 +366,23 @@ 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 actually
+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.
+
+Each externally maintained package lives in its own subdirectory in
+the Emacs tree, and that subdirectory should have a "README" file that
+describes the upstream origin.  For example, "lisp/org/README" says
+where the Org Mode project lives and how it's synchronized into Emacs.
+
+Note that not all the independently-maintained packages in Emacs have
+such a "README" yet.  If you know of one that's missing its "README",
+please send in a patch or just let us know.
+
 ** GNU ELPA
 
 This repository does not contain the Emacs Lisp package archive
diff --git lisp/org/README lisp/org/README
new file mode 100644
index 0000000000..f9fe1e6edc
--- /dev/null
+++ lisp/org/README
@@ -0,0 +1,6 @@
+Org Mode is maintained as a separate project, and is periodically
+merged into Emacs.
+
+See https://orgmode.org/ for more information, and see specifically
+https://orgmode.org/worg/org-maintenance.html for information about
+the process of synchronization between upstream Org Mode and Emacs.
-- 
2.34.1