Re: Improving documentation of Org Mode integration into Emacs.

[Karl Fogel]

On 10 Jan 2022, Michael Albinus wrote:
> > > 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?
>
> It is OK to be listed there. I just don't want to *urge* people 
> to use
> the Tramp repo, unless it is needed.

Hmm, but how will they know whether it is needed?  Perhaps the new 
"Notes" field in the Tramp entry could give some guidance on that.

The original goal of this change was to provide guidance to 
contributors who might otherwise waste time doing the wrong thing. 
For example, they might fail to check upstream to see if a bug has 
already been fixed there, or is being discussed there; or they 
might send a contribution to Emacs when really it should be sent 
somewhere else; etc.

So if there are circumstances in which contributors should worry 
about these possibilities for Tramp, then the Tramp entry in that 
file should explain what those circumstances are -- this is, after 
all, what the entry is for :-).

> And the information about Tramp's bug tracker and backward 
> compatibility (just pushed to the repo) makes it worthwile.

Got it.  So it sounds like the "Notes" field should give some 
advice about checking the upstream sources and bug tracker first, 
when trying to find out if a bug is already known/addressed.  And 
if you're happy to accept patches against the sources shipped in 
Emacs, even when those sources are slightly out-of-date with 
respect to what you have upstream, then "Notes" can say that too.

Thoughts?

Best regards,
-Karl