Re: Improving documentation of Org Mode integration into Emacs.

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Date: Sun, 09 Jan 2022 16:34:16 -0600
> 
> --- 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.

This is okay, but I'd lose the last sentence: it isn't different from
saying "if you see something wrong in Emacs, please submit a patch".

> +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.

I'd lose the two last paragraphs.  They are not really needed for
people to report issues with Org.  If/when someone becomes intimately
involved with Org development, they will learn those aspects; but it
is not the job of CONTRIBUTE or MAINTAINERS to teach them that.

Thanks.