Re: Improving documentation of Org Mode integration into Emacs.

[Karl Fogel]

On 10 Jan 2022, Eli Zaretskii wrote:
> > +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".

Okay.  I'll commit with changes as noted previously in this thread 
and in this email.  I may change the wording of the previous 
sentence above to somehow express the point that the list in 
admin/MAINTAINERS is not guaranteed to be complete.

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

Okay.

> > 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.
>
> IMO, that'd be in the "too much information" department.
>
> We don't need to say everything there, just enough for the people 
> to
> know how to handle a bug report without wasting their time and 
> ours.

We have different judgement about what type of information to 
include in these entries, but at this point the differences are 
small, and probably most contributors will be able to figure 
things out.  I'll eliminate those two paragraphs.

Thanks for the review, Eli.

Best regards,
-Karl