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