From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Karl Fogel Newsgroups: gmane.emacs.devel Subject: Re: Improving documentation of Org Mode integration into Emacs. Date: Tue, 04 Jan 2022 21:09:47 -0600 Message-ID: <87ee5mlvyc.fsf@red-bean.com> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.fsf@gnu.org> <87fsq5tnni.fsf@red-bean.com> Reply-To: Karl Fogel Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15463"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Jan 05 04:33:55 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1n4x3i-0003mO-ML for ged-emacs-devel@m.gmane-mx.org; Wed, 05 Jan 2022 04:33:55 +0100 Original-Received: from localhost ([::1]:44218 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n4x3h-0005S5-E0 for ged-emacs-devel@m.gmane-mx.org; Tue, 04 Jan 2022 22:33:53 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:60660) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4wgT-00080S-8q for emacs-devel@gnu.org; Tue, 04 Jan 2022 22:09:54 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:43420) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4wgQ-00022m-CQ for emacs-devel@gnu.org; Tue, 04 Jan 2022 22:09:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=red-bean.com; s=202005newsp; h=Content-Type:MIME-Version:Message-ID: In-Reply-To:Date:Reply-To:References:Subject:To:From:Sender:Cc: Content-Transfer-Encoding:Content-ID:Content-Description; bh=0I/ehWv7wR4roXx+3qoC+LmTKEotPUPf7CNbDEvjCqc=; t=1641352189; x=1642561789; b=DVP2diIPX5XpYWamk88NLh+A1ictPcmZdo/KamPunGHfQCO1CxIdrDd+8bNjF0B1jIrTpZyJJQ8 4QCq70ubMITRxcZ5rb1ImYl1SKSSDN9BVwRDTEE6U9Op6YbhEIxLnpOA0lIb/XLt+uIdt1d5NSkS5 BQ6SkWi0v4EW5KMo45zpgzVPrySKXaotTt3TfKmzVIwCGk4U/kwPkXcdfiOApZmrUoOiK1HZ2nT6O OQILMo0dpc/kT+2XWX+x+wrgmDwYPwdK9L/f9qOdr6ZDu1IMtYdRd/D4h2fdqNEb4jV/mqcj5aEzA 5J4Z+a5HkFvdxA139Cv1INiJPH/uoMl9A80A==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60418 helo=floss) by sanpietro.red-bean.com with esmtpsa (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1n4wgN-00GYbm-SG for emacs-devel@gnu.org; Wed, 05 Jan 2022 03:09:47 +0000 In-Reply-To: (Stefan Monnier's message of "Mon, 03 Jan 2022 00:44:30 -0500") Received-SPF: pass client-ip=45.79.25.59; envelope-from=kfogel@red-bean.com; helo=sanpietro.red-bean.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:284207 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Replying to several emails together here -- from Stefan, Michael,=20 Protesilaos, Rudolf, and Eli -- as they're related. TL;DR: Just=20 see the attached revised patch, which incorporates information and=20 suggestions from those folks. On 03 Jan 2022, Stefan Monnier wrote:=20 >"Externally maintained" might not be quite right for the=20 >following packages, but they do fit the description to some=20 >extent in the sense that the maintainer also distributes the code=20 >elsewhere (e.g. for XEmacs): - CC-mode - VHDL-mode - Verilog-mode=20 =20 Well, the question isn't about whether the code is also=20 distributed elsewhere. Rather, the question is "Where should a=20 developer go first with bug reports, bug patches, enhancement=20 suggestions, etc?" If she should go to Emacs Devel (or our=20 debbugs tracker) first, then no special note is needed. If she=20 should go to some other upstream origin first, or should at least=20 consider doing that, then a note is needed. (For the above three=20 packages specifically, I don't know the answer to that question,=20 as I haven't looked at them in depth.) On 03 Jan 2022, Michael=20 Albinus wrote:=20 >> +Each externally maintained package lives in its own=20 >> subdirectory in +the Emacs tree, and that subdirectory should=20 >> have a "README" file that +describes the upstream origin. For=20 >> example, "lisp/org/README" says +where the Org Mode project=20 >> lives and how it's synchronized into Emacs.=20 > That's not the case now. Tramp, for example, does not live in an=20 >own subdirectory. Should it?=20 =20 Ah, thank you for pointing this out. Okay, there are two=20 different ways we could handle that: 1) Document the current=20 messy reality (described in detail below). 2) Clean up reality,=20 then document that new reality :-). I think (1) is better right=20 now, as it's a smaller change. The "messy reality" I'm referring=20 to is this: *Some* multi-file externally maintained packages,=20 like Tramp, are not contained in a dedicated subdirectory. All=20 the Tramp files live in "lisp/net/", alongside other non-Tramp=20 file (some of which are also multi-file packages, like EUDC,=20 although unlike Tramp they are not externally maintained packages=20 as far as I know). Meanwhile, *other* multi-file externally=20 maintained packages, such as Org Mode, do have their own dedicated=20 subdirectory (e.g., "lisp/org/"). In these cases, there is as=20 easy solution for documenting the fact of external maintenance:=20 put a README in that subdir. The attached revised patch shows=20 this. Doing (2) would mean putting every multi-file package into=20 its own dedicated subdirectory (e.g., "lisp/net/tramp/") -- for=20 both externally and internally maintained packages. I think this=20 would be a good organizational improvement for us to make anyway,=20 not only because it would simplify our strategy for documenting=20 external maintenance for multi-file packages. But (1) seems like=20 the right option here, as it's a smaller step. (2) would be a=20 separate decision that goes beyond the scope of my original=20 proposal.=20 On 03 Jan 2022, Protesilaos Stavrou wrote:=20 >The modus-themes are maintained externally. I sync them with=20 >emacs.git every month or so when I release a new version. Their=20 >.el files are in etc/themes/ while the manual is in doc/misc/.=20 >I am happy to provide a README, though neither of those two=20 >directories is specific to the modus-themes. Maybe I should=20 >include the relevant information in the themes' manual and/or the=20 >"Commentary:" of each .el file?=20 =20 Thanks for mentioning these. Please see the attached patch, which=20 I think might answer your question (in the diff to CONTRIBUTE).=20 On 03 Jan 2022, Rudolf Adamkovi=C4=8D 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=20 new patch attached here. On 03 Jan 2022, Eli Zaretskii wrote:=20 >Thanks. However, IMO the text as written doesn't belong to=20 >CONTRIBUTE. That file includes actionable instructions to=20 >contributors regarding our development procedures, conventions,=20 >and requirements. The purpose of those instructions is to make=20 >the contributed changes acceptable and matching our practices.=20 >By contrast, the text that you propose is just information that=20 >is not actionable. So if this text is to stay in its present=20 >form, it should be somewhere else, perhaps in README. If you do=20 >want it to be in CONTRIBUTE, it mostly be comprised of some=20 >specific instructions what to do or what not to do. The purely=20 >informational part should ideally be shorter and more focused on=20 >what contributors need to know in order to, well, contribute.=20 =20 The attached (revised) patch gives some specific instructions as=20 examples. But CONTRIBUTE's job is just to explain the general=20 situation about externally maintained packages and give a few=20 examples, so that developers understand why they need to be watch=20 out for this situation. That's what the revised text in the=20 attached patch does. Let me explain more clearly why I think=20 CONTRIBUTE needs this section: The CONTRIBUTE file is where=20 developers go to learn how to contribute to Emacs. But right now,=20 when a developer finds a bug in (or wants to make an improvement=20 to) a package that is distributed with Emacs but is externally=20 maintained, she could easily miss the fact that the package is=20 externally maintained! That means she'll often bring her bug=20 report or enhancement suggestion to the wrong place first: Emacs's=20 own forums, instead of to the true upstream forums. In other=20 words, CONTRIBUTE needs to document this phenomenon because=20 CONTRIBUTE is where we point developers to to learn how to=20 contribute to Emacs -- and this information is about routing=20 contributions correctly. But CONTRIBUTE shouldn't give the=20 specific instructions for each package. It should just show the=20 developer how to figure out if a package is externally maintained,=20 and then that package can point the developer in the right=20 direction in whatever way is most appropriate. >Please note that none of what you say here is in the text, not=20 >even as a hint. If the idea is to tell contributors to direct=20 >bug reports for those packages elsewhere, why not tell that=20 >explicitly, and why not include the relevant URLs where those=20 >bugs should be reported?=20 =20 This is made more explicit now in CONTRIBUTE. Again, I don't include all the specific upstream URLs in=20 CONTRIBUTE because we're not listing all the externally maintained=20 packages in CONTRIBUTE. CONTRIBUTE just explains how to detect=20 such a package, and then lets the package's files give the proper=20 pointers.=20 =20 >> +See https://orgmode.org/ for more information, and see=20 >> specifically +https://orgmode.org/worg/org-maintenance.html for=20 >> information about +the process of synchronization between=20 >> upstream Org Mode and Emacs.=20 > The beginning of this is promising, but then it strays: instead=20 >of telling people to send patches and bug reports about Org to=20 >those addresses and not to Emacs's tracker, it invites them to=20 >learn about the process of synchronization between Org and Emacs,=20 >something that I think is of secondary importance (to say the=20 >least) for causal contributors.=20 =20 Thanks; good idea. I've improved the proposed lisp/org/README as=20 you indicate above. The new language also makes clearer why -- in=20 the specific case of Org Mode -- one might want to learn about the=20 process of synchronization, since with Org Mode changes flow=20 bidirectionally (which may not be the case for all externally=20 maintained packages). Best regards, -Karl --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0001-Document-external-maintenance-of-some-packages.patch Content-Description: [PATCH] Document external maintenance of some packages >From 79527535f74b8299fa2d1612d0458d4972e05ac1 Mon Sep 17 00:00:00 2001 From: Karl Fogel Date: Sun, 2 Jan 2022 22:49:35 -0600 Subject: [PATCH] Document external maintenance of some packages Document the fact that some packages in Emacs are externally maintained and document how to discover their upstream origin. For more context, see the thread that starts here: https://lists.gnu.org/archive/html/emacs-devel/2021-12/msg00366.html From: Karl Fogel To: Emacs Devel Subject: Improving documentation of Org Mode integration into Emacs. Date: Sat, 04 Dec 2021 15:14:59 -0600 Message-ID: <87zgpgax7w.fsf@red-bean.com> --- CONTRIBUTE | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ lisp/org/README | 19 +++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 lisp/org/README diff --git CONTRIBUTE CONTRIBUTE index 7c3421ed75..527ad1ed35 100644 --- CONTRIBUTE +++ CONTRIBUTE @@ -366,6 +366,55 @@ reasons. These should be marked by including something like "Do not merge to master" or anything that matches gitmerge-skip-regexp (see admin/gitmerge.el) in the commit message. +** Some packages in Emacs are maintained externally + +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. For example, if you're trying to fix a bug, you should obtain +the latest version of the packages's code from that upstream source, +since that code will likely be ahead of whatever version is in Emacs +and you'll want to test the latest code to see if the bug is still +present. Likewise, if you're starting a development discussion, you +should generally do so in the package's own forums rather than in +Emacs's forums; the upstream developers can provide guidance about +whether Emacs's developers need to be brought in to the discussion. + +*** How to tell which packages are externally maintained + +When an externally maintained package is just one file, then a comment +near the top of the file should indicate the upstream origin. + +When an externally maintained package involves multiple files, then +there are a couple of possibilities: + +1. The files all live in one dedicated subdirectory that is specific + to that package. In this case, there should be a README in that + subdirectory indicating the upstream origin. For example, + "lisp/org/README" indicates where the Org Mode project lives and + what that provenance implies for contributors. + +2. The package's files all live in the same directory, and share a + common filename prefix, but there are also other files in that + directory that are unrelated to the package in question. + + In this case, there should be a comment near the top of the + package's main entry-point file -- i.e., the file that one loads to + `provide' the package -- giving the provenance indication. For + example, the Tramp package is made up of multiple files + ("lisp/net/tramp*") and the package's upstream origin is described + in a comment near the top of "lisp/net/tramp.el". + +Note that there may be some independently-maintained packages in Emacs +that still lack a clear provenance indicator. If you find one, please +send in a patch or just let us know. + ** GNU ELPA This repository does not contain the Emacs Lisp package archive diff --git lisp/org/README lisp/org/README new file mode 100644 index 0000000000..6c8022f56a --- /dev/null +++ lisp/org/README @@ -0,0 +1,19 @@ +Org Mode is maintained as a separate project, and 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). + +Thus, 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. Either way, this is something you +will need to know in order to know where to contribute your fix. -- 2.34.1 --=-=-=--