Re: Improving documentation of Org Mode integration into Emacs.

[Eli Zaretskii <eliz@gnu.org>]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Sun, 02 Jan 2022 23:05:05 -0600
> 
> >> I'd like to improve our in-tree documentation of how Org Mode 
> >> integration into GNU Emacs works.
> >
> >Thanks.  Can you provide a rough sketch, in the form of list of 
> >items,
> >of what you'd like to document, and who would be the main 
> >audience for
> >that?  I don't have a clear idea of that based on what you 
> >posted.
> 
> Sure.  (The attached patch may answer your questions more 
> efficiently, though.)

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.

> It's better for us all if such a person finds out as soon as 
> possible where the active upstream for a package is.  For example, 
> if they've found a bug in Org Mode, they should take the bug 
> report to the Org Mode forums and discuss it with the Org Mode 
> maintainers.  (Maybe sometimes Emacs Devel should also be 
> involved, but the person should at least start out in the proper 
> upstream forum and then be guided appropriately from there.)

Please note that none of what you say here is in the text, not even as
a hint.  If the idea is to tell contributors to direct bug reports for
those packages elsewhere, why not tell that explicitly, and why not
include the relevant URLs where those bugs should be reported?

> +See https://orgmode.org/ for more information, and see specifically
> +https://orgmode.org/worg/org-maintenance.html for information about
> +the process of synchronization between upstream Org Mode and Emacs.

The beginning of this is promising, but then it strays: instead of
telling people to send patches and bug reports about Org to those
addresses and not to Emacs's tracker, it invites them to learn about
the process of synchronization between Org and Emacs, something that I
think is of secondary importance (to say the least) for causal
contributors.