Re: Improving documentation of Org Mode integration into Emacs.

[Karl Fogel]

On 10 Jan 2022, Michael Albinus wrote:
> > * 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.
>
> That's OK. Org-mode has a lot of own test files not integrated 
> into
> Emacs repo; I hope we can get them too.

I hope so too.  However, for our purposes here, we don't care 
about files on the Org Mode side that aren't currently integrated 
into Emacs's repository; we only care about what's present in 
Emacs.

> > +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.
>
> I'm not sure that this is always the case. For Tramp, I'm happy 
> if
> people refer to the Emacs repo files; sync with the upstream 
> package is
> something contributors don't need to worry about. We shall keep 
> the
> barrier low.

Hmmm.  In that case, should Tramp be listed in the "Externally 
maintained packages" section of admin/MAINTAINERS at all?

The purpose of that section, and of the new material in 
CONTRIBUTE, is to make contributors be aware of the situations in 
which they *do* need to pay attention to the fact of external 
maintenance -- that is, situations in which contributors might 
need to do something differently from how one would normally do 
it.

In situations where they can just send their contribution to Emacs 
in the usual Emacs-y way, then there is no need for special 
documentation in the first place.

We could change "often" to "sometimes" in the above-quoted text, 
but I think it's worth asking if Tramp should even be listed, if 
Tramp is happy to receive contributions via the usual Emacs 
project route anyway.

> More important are compatibility restrictions. All of these 
> externally
> maintained packages have their policy, we shall advice potential
> contributors to respect them. Refer to the respective 
> Package-Requires:
> header line.
>
> > +Org Mode
> > +       Home Page: https://orgmode.org/
> > +       Maintainer: Org Mode developers
>
> The sync between org-mode and Emacs is performed by Kyle Meyer
> <kyle@kyleam.com>, shall we mention him as the guy to be 
> contacted in
> case of?

IMHO Emacs should avoid duplicating documentation that's available 
from the upstream projects themselves.  We should just send people 
upstream to get the latest information, whether about 
compatibility guidelines or anything else.

In fact, I wasn't even sure about listing the Org Mode version 
control repository explicitly in the section I added; I only did 
it for consistency with the other similar sections.  Ideally, the 
contributor should just go look at orgmode.org (or whatever the 
appropriate upstream landing page is, for other packages) and 
follow the pointers there.

The reason I added the long note in the Org Mode section is that 
Org Mode's situation is unusually complex, and AFAIK it's not 
summarized like that -- i.e., from the GNU Emacs development point 
of view -- on Org Mode's own site.

Best regards,
-Karl