Re: Improving documentation of Org Mode integration into Emacs.

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Date: Tue, 04 Jan 2022 21:09:47 -0600
> 
> On 03 Jan 2022, Eli Zaretskii wrote: 
> >Thanks.   However, IMO the text as written doesn't belong to 
> >CONTRIBUTE.  That file includes actionable instructions to 
> >contributors regarding our development procedures, conventions, 
> >and requirements.  The purpose of those instructions is to make 
> >the contributed changes acceptable and matching our practices. 
> >By contrast, the text that you propose is just information that 
> >is not actionable.  So if this text is to stay in its present 
> >form, it should be somewhere else, perhaps in README.   If you do 
> >want it to be in CONTRIBUTE, it mostly be comprised of some 
> >specific instructions what to do or what not to do.  The purely 
> >informational part should ideally be shorter and more focused on 
> >what contributors need to know in order to, well, contribute. 
>  
> The attached (revised) patch gives some specific instructions as 
> examples.

I don't think providing just examples is the best idea.  See below.

> But CONTRIBUTE's job is just to explain the general 
> situation about externally maintained packages and give a few 
> examples, so that developers understand why they need to be watch 
> out for this situation.

I think we should explain the issue concisely, and then provide
specific instructions.  This text is IMO enough for the first part:

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

Following that, we should provide a full, exhaustive list of all such
packages in Emacs core, each one with a corresponding URL (mailing
list, upstream repository with an issue tracker, etc.).  It might be a
good idea to have this list on a separate file, perhaps in etc/, and
only have CONTRIBUTE point to that file.

> But CONTRIBUTE shouldn't give the specific instructions for each
> package.  It should just show the developer how to figure out if a
> package is externally maintained, and then that package can point
> the developer in the right direction in whatever way is most
> appropriate.

I disagree.  If we don't provide a full list of such packages with
precise instructions, we will not make any significant progress:
people would still need to ask us about the details, when they aren't
"smart" enough (or patient enough) to read the instructions that teach
them how to deduce that by themselves.  Moreover, as you have found
out already, there's no standard way such packages use to "plug"
themselves into Emacs, so it's likely that any general instructions we
provide will be inaccurate in some cases.  An exhaustive "cookbook" is
much better, IMO, and is easier to maintain in the long run.  It will
also be shorter, which is a nice bonus, given today's "TL;DR"
attitude.

Thanks.