From: Karl Fogel <kfogel@red-bean.com>
To: Michael Albinus <michael.albinus@gmx.de>
Cc: Kyle Meyer <kyle@kyleam.com>, emacs-devel@gnu.org
Subject: Re: Improving documentation of Org Mode integration into Emacs.
Date: Mon, 10 Jan 2022 03:06:11 -0600 [thread overview]
Message-ID: <87bl0kgdto.fsf@red-bean.com> (raw)
In-Reply-To: <87czl0j7vf.fsf@gmx.de> (Michael Albinus's message of "Mon, 10 Jan 2022 09:46:28 +0100")
On 10 Jan 2022, Michael Albinus wrote:
>> * In admin/MAINTAINERS, I did not list
>> "test/lisp/org/org-tests.el"
>> as a file maintained by the Org Mode project, because it
>> looks
>> like that file exists only in Emacs and is not shipped with
>> Org
>> Mode.
>
>That's OK. Org-mode has a lot of own test files not integrated
>into
>Emacs repo; I hope we can get them too.
I hope so too. However, for our purposes here, we don't care
about files on the Org Mode side that aren't currently integrated
into Emacs's repository; we only care about what's present in
Emacs.
>> +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.
>
>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?
The purpose of that section, and of the new material in
CONTRIBUTE, is to make contributors be aware of the situations in
which they *do* need to pay attention to the fact of external
maintenance -- that is, situations in which contributors might
need to do something differently from how one would normally do
it.
In situations where they can just send their contribution to Emacs
in the usual Emacs-y way, then there is no need for special
documentation in the first place.
We could change "often" to "sometimes" in the above-quoted text,
but I think it's worth asking if Tramp should even be listed, if
Tramp is happy to receive contributions via the usual Emacs
project route anyway.
>More important are compatibility restrictions. All of these
>externally
>maintained packages have their policy, we shall advice potential
>contributors to respect them. Refer to the respective
>Package-Requires:
>header line.
>
>> +Org Mode
>> + Home Page: https://orgmode.org/
>> + Maintainer: Org Mode developers
>
>The sync between org-mode and Emacs is performed by Kyle Meyer
><kyle@kyleam.com>, shall we mention him as the guy to be
>contacted in
>case of?
IMHO Emacs should avoid duplicating documentation that's available
from the upstream projects themselves. We should just send people
upstream to get the latest information, whether about
compatibility guidelines or anything else.
In fact, I wasn't even sure about listing the Org Mode version
control repository explicitly in the section I added; I only did
it for consistency with the other similar sections. Ideally, the
contributor should just go look at orgmode.org (or whatever the
appropriate upstream landing page is, for other packages) and
follow the pointers there.
The reason I added the long note in the Org Mode section is that
Org Mode's situation is unusually complex, and AFAIK it's not
summarized like that -- i.e., from the GNU Emacs development point
of view -- on Org Mode's own site.
Best regards,
-Karl
next prev parent reply other threads:[~2022-01-10 9:06 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-04 21:14 Improving documentation of Org Mode integration into Emacs Karl Fogel
2021-12-04 21:18 ` Karl Fogel
2021-12-04 22:09 ` [External] : " Drew Adams
2021-12-05 5:16 ` Stefan Monnier
2021-12-05 6:38 ` Eli Zaretskii
2022-01-03 5:05 ` Karl Fogel
2022-01-03 5:44 ` Stefan Monnier
2022-01-05 3:09 ` Karl Fogel
2022-01-05 13:48 ` Eli Zaretskii
2022-01-05 14:17 ` Michael Albinus
2022-01-05 14:26 ` Eli Zaretskii
2022-01-06 12:40 ` Michael Albinus
2022-01-06 13:58 ` Eli Zaretskii
2022-01-07 10:41 ` Protesilaos Stavrou
2022-01-09 22:34 ` Karl Fogel
2022-01-10 8:46 ` Michael Albinus
2022-01-10 9:03 ` Michael Albinus
2022-01-10 9:13 ` Karl Fogel
2022-01-10 9:17 ` Michael Albinus
2022-01-10 11:01 ` Robert Pluim
2022-01-10 16:10 ` Karl Fogel
2022-01-10 9:06 ` Karl Fogel [this message]
2022-01-10 9:24 ` Michael Albinus
2022-01-10 16:20 ` Karl Fogel
2022-01-10 18:24 ` Eli Zaretskii
2022-01-11 7:49 ` Michael Albinus
2022-01-10 18:14 ` Eli Zaretskii
2022-01-10 19:08 ` Karl Fogel
2022-01-03 8:52 ` Michael Albinus
2022-01-03 12:06 ` Protesilaos Stavrou
2022-01-03 13:31 ` Eli Zaretskii
2022-01-03 20:45 ` Rudolf Adamkovič
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87bl0kgdto.fsf@red-bean.com \
--to=kfogel@red-bean.com \
--cc=emacs-devel@gnu.org \
--cc=kyle@kyleam.com \
--cc=michael.albinus@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).