From 79527535f74b8299fa2d1612d0458d4972e05ac1 Mon Sep 17 00:00:00 2001 From: Karl Fogel 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 how to discover their upstream origin. 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 | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ lisp/org/README | 19 +++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 lisp/org/README diff --git CONTRIBUTE CONTRIBUTE index 7c3421ed75..527ad1ed35 100644 --- CONTRIBUTE +++ CONTRIBUTE @@ -366,6 +366,55 @@ 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. For example, if you're trying to fix a bug, you should obtain +the latest version of the packages's code from that upstream source, +since that code will likely be ahead of whatever version is in Emacs +and you'll want to test the latest code to see if the bug is still +present. Likewise, if you're starting a development discussion, you +should generally do so in the package's own forums rather than in +Emacs's forums; the upstream developers can provide guidance about +whether Emacs's developers need to be brought in to the discussion. + +*** How to tell which packages are externally maintained + +When an externally maintained package is just one file, then a comment +near the top of the file should indicate the upstream origin. + +When an externally maintained package involves multiple files, then +there are a couple of possibilities: + +1. The files all live in one dedicated subdirectory that is specific + to that package. In this case, there should be a README in that + subdirectory indicating the upstream origin. For example, + "lisp/org/README" indicates where the Org Mode project lives and + what that provenance implies for contributors. + +2. The package's files all live in the same directory, and share a + common filename prefix, but there are also other files in that + directory that are unrelated to the package in question. + + In this case, there should be a comment near the top of the + package's main entry-point file -- i.e., the file that one loads to + `provide' the package -- giving the provenance indication. For + example, the Tramp package is made up of multiple files + ("lisp/net/tramp*") and the package's upstream origin is described + in a comment near the top of "lisp/net/tramp.el". + +Note that there may be some independently-maintained packages in Emacs +that still lack a clear provenance indicator. If you find one, 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..6c8022f56a --- /dev/null +++ lisp/org/README @@ -0,0 +1,19 @@ +Org Mode is maintained as a separate project, and 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). + +Thus, 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. Either way, this is something you +will need to know in order to know where to contribute your fix. -- 2.34.1