[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Improving documentation of Org Mode integration into Emacs.
From: |
Karl Fogel |
Subject: |
Re: Improving documentation of Org Mode integration into Emacs. |
Date: |
Tue, 04 Jan 2022 21:09:47 -0600 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) |
Replying to several emails together here -- from Stefan, Michael,
Protesilaos, Rudolf, and Eli -- as they're related. TL;DR: Just
see the attached revised patch, which incorporates information and
suggestions from those folks.
On 03 Jan 2022, Stefan Monnier wrote:
"Externally maintained" might not be quite right for the
following packages, but they do fit the description to some
extent in the sense that the maintainer also distributes the code
elsewhere (e.g. for XEmacs): - CC-mode - VHDL-mode - Verilog-mode
Well, the question isn't about whether the code is also
distributed elsewhere. Rather, the question is "Where should a
developer go first with bug reports, bug patches, enhancement
suggestions, etc?" If she should go to Emacs Devel (or our
debbugs tracker) first, then no special note is needed. If she
should go to some other upstream origin first, or should at least
consider doing that, then a note is needed. (For the above three
packages specifically, I don't know the answer to that question,
as I haven't looked at them in depth.) On 03 Jan 2022, Michael
Albinus wrote:
+Each externally maintained package lives in its own
subdirectory in +the Emacs tree, and that subdirectory should
have a "README" file that +describes the upstream origin. For
example, "lisp/org/README" says +where the Org Mode project
lives and how it's synchronized into Emacs.
That's not the case now. Tramp, for example, does not live in an
own subdirectory. Should it?
Ah, thank you for pointing this out. Okay, there are two
different ways we could handle that: 1) Document the current
messy reality (described in detail below). 2) Clean up reality,
then document that new reality :-). I think (1) is better right
now, as it's a smaller change. The "messy reality" I'm referring
to is this: *Some* multi-file externally maintained packages,
like Tramp, are not contained in a dedicated subdirectory. All
the Tramp files live in "lisp/net/", alongside other non-Tramp
file (some of which are also multi-file packages, like EUDC,
although unlike Tramp they are not externally maintained packages
as far as I know). Meanwhile, *other* multi-file externally
maintained packages, such as Org Mode, do have their own dedicated
subdirectory (e.g., "lisp/org/"). In these cases, there is as
easy solution for documenting the fact of external maintenance:
put a README in that subdir. The attached revised patch shows
this. Doing (2) would mean putting every multi-file package into
its own dedicated subdirectory (e.g., "lisp/net/tramp/") -- for
both externally and internally maintained packages. I think this
would be a good organizational improvement for us to make anyway,
not only because it would simplify our strategy for documenting
external maintenance for multi-file packages. But (1) seems like
the right option here, as it's a smaller step. (2) would be a
separate decision that goes beyond the scope of my original
proposal.
On 03 Jan 2022, Protesilaos Stavrou wrote:
The modus-themes are maintained externally. I sync them with
emacs.git every month or so when I release a new version. Their
.el files are in etc/themes/ while the manual is in doc/misc/.
I am happy to provide a README, though neither of those two
directories is specific to the modus-themes. Maybe I should
include the relevant information in the themes' manual and/or the
"Commentary:" of each .el file?
Thanks for mentioning these. Please see the attached patch, which
I think might answer your question (in the diff to CONTRIBUTE).
On 03 Jan 2022, Rudolf Adamkovič wrote:
I have a small comment. :)
I think we can drop the word "actually" from the first sentence:
I agree -- thank you. Your suggestion is incorporated into the
new patch attached here.
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. 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. That's what the revised text in the
attached patch does. Let me explain more clearly why I think
CONTRIBUTE needs this section: The CONTRIBUTE file is where
developers go to learn how to contribute to Emacs. But right now,
when a developer finds a bug in (or wants to make an improvement
to) a package that is distributed with Emacs but is externally
maintained, she could easily miss the fact that the package is
externally maintained! That means she'll often bring her bug
report or enhancement suggestion to the wrong place first: Emacs's
own forums, instead of to the true upstream forums. In other
words, CONTRIBUTE needs to document this phenomenon because
CONTRIBUTE is where we point developers to to learn how to
contribute to Emacs -- and this information is about routing
contributions correctly. 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.
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?
This is made more explicit now in CONTRIBUTE.
Again, I don't include all the specific upstream URLs in
CONTRIBUTE because we're not listing all the externally maintained
packages in CONTRIBUTE. CONTRIBUTE just explains how to detect
such a package, and then lets the package's files give the proper
pointers.
+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.
Thanks; good idea. I've improved the proposed lisp/org/README as
you indicate above. The new language also makes clearer why -- in
the specific case of Org Mode -- one might want to learn about the
process of synchronization, since with Org Mode changes flow
bidirectionally (which may not be the case for all externally
maintained packages).
Best regards,
-Karl
0001-Document-external-maintenance-of-some-packages.patch
Description: [PATCH] Document external maintenance of some packages
- Re: Improving documentation of Org Mode integration into Emacs., Karl Fogel, 2022/01/03
- Re: Improving documentation of Org Mode integration into Emacs., Stefan Monnier, 2022/01/03
- Re: Improving documentation of Org Mode integration into Emacs.,
Karl Fogel <=
- Re: Improving documentation of Org Mode integration into Emacs., Eli Zaretskii, 2022/01/05
- Re: Improving documentation of Org Mode integration into Emacs., Michael Albinus, 2022/01/05
- Re: Improving documentation of Org Mode integration into Emacs., Eli Zaretskii, 2022/01/05
- Re: Improving documentation of Org Mode integration into Emacs., Michael Albinus, 2022/01/06
- Re: Improving documentation of Org Mode integration into Emacs., Eli Zaretskii, 2022/01/06
- Re: Improving documentation of Org Mode integration into Emacs., Protesilaos Stavrou, 2022/01/07
- Re: Improving documentation of Org Mode integration into Emacs., Karl Fogel, 2022/01/09
- Re: Improving documentation of Org Mode integration into Emacs., Michael Albinus, 2022/01/10
- Re: Improving documentation of Org Mode integration into Emacs., Michael Albinus, 2022/01/10
- Re: Improving documentation of Org Mode integration into Emacs., Karl Fogel, 2022/01/10