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: Sun, 09 Jan 2022 16:34:16 -0600 Message-ID: <87zgo4v8rb.fsf@red-bean.com> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.fsf@gnu.org> <87fsq5tnni.fsf@red-bean.com> <87ee5mlvyc.fsf@red-bean.com> <83lezu9tv1.fsf@gnu.org> 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="35535"; 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 Sun Jan 09 23:35:40 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 1n6gmp-00094M-ET for ged-emacs-devel@m.gmane-mx.org; Sun, 09 Jan 2022 23:35:39 +0100 Original-Received: from localhost ([::1]:32926 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n6gmo-0003av-4r for ged-emacs-devel@m.gmane-mx.org; Sun, 09 Jan 2022 17:35:38 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:54968) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6gla-00029w-Dd for emacs-devel@gnu.org; Sun, 09 Jan 2022 17:34:22 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:53014) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6glY-0008UT-03 for emacs-devel@gnu.org; Sun, 09 Jan 2022 17:34:22 -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=Jb7eYKm0e1JV67b5KFK0/aYX8Q3qpVqDS31AEFleKXo=; t=1641767658; x=1642977258; b=f9Axtz71pZ9hh3arE9p1KNh3U0TCs7FOhe64BTrVBaXP/0ql0rc51r8quliJKXCQeU3rTWaVD8H +YHa0GyVEaI78zEvBP6tcUs3ldnodRvMe/0pujvsnrj7VDTtIrCR49BllyD+KVYICsfWp3jKklbNV sUFofECVL3qhwt4I1HSbOkktE47UCoNMftzS9vD3MJgt4OI/t4qj3CNdPD+awmhKfomnIGJbbuc1g y1HUGlnpOFsoNkaA+cM2f0ohPwH3o5lLKqTaS/8IWmZzK7H+NjXfL7X6Ww6FU58u7F8yTA0MEfKhh yl72ha+mDWtvILNoOfx/tOb9fp/17/L6n00Q==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60490 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 1n6glU-000yIN-Qj for emacs-devel@gnu.org; Sun, 09 Jan 2022 22:34:17 +0000 In-Reply-To: <83lezu9tv1.fsf@gnu.org> (Eli Zaretskii's message of "Wed, 05 Jan 2022 15:48:02 +0200") 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:284509 Archived-At: --=-=-= Content-Type: text/plain; format=flowed On 05 Jan 2022, Eli Zaretskii wrote: >I think we should explain the issue concisely, and then provide >specific instructions. This text is IMO enough for the first >part: > >[...] > >Following that, we should provide a full, exhaustive list of all >such >packages in Emacs core, each one with a corresponding URL >(mailing >list, upstream repository with an issue tracker, etc.). It might >be a >good idea to have this list on a separate file, perhaps in etc/, >and >only have CONTRIBUTE point to that file. The attached patch puts a concise text in CONTRIBUTE as you described, and adds an entry for Org Mode to the new "Externally maintained packages" section of admin/MAINTAINERS -- following Michael Albinius's and Protesilaos Stavrou's lead re Tramp and Modus Themes respectively. The Org Mode entry is larger than the Tramp and Modus Themes entries, because the situation with Org Mode is more complex. That's why I've attached this patch for review instead of just committing it. >I disagree. If we don't provide a full list of such packages >with >precise instructions, we will not make any significant progress: >people would still need to ask us about the details, when they >aren't >"smart" enough (or patient enough) to read the instructions that >teach >them how to deduce that by themselves. Moreover, as you have >found >out already, there's no standard way such packages use to "plug" >themselves into Emacs, so it's likely that any general >instructions we >provide will be inaccurate in some cases. An exhaustive >"cookbook" is >much better, IMO, and is easier to maintain in the long run. It >will >also be shorter, which is a nice bonus, given today's "TL;DR" >attitude. That's persuasive; I think it's a good solution. Feedback on the attached patch is welcome. A couple of notes about it: * Although the "Branches" section in CONTRIBUTE implies that these changes should go on the "emacs-28" branch, this patch is against "master" because Michael and Protesilaos committed their changes to "master". (I think it's all fine on "master" too, and the guidance in CONTRIBUTE is a bit ambiguous about this kind of change anyway.) * 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. 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 6a9a0132b7313a16539b2ec8b3fb9cac390b5915 Mon Sep 17 00:00:00 2001 From: Karl Fogel Date: Sun, 9 Jan 2022 16:07:08 -0600 Subject: [PATCH] Document external maintenance of some packages Document the fact that some packages in Emacs are externally maintained, and specifically document Org Mode's external maintenance. 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 | 18 ++++++++++++++++++ admin/MAINTAINERS | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git CONTRIBUTE CONTRIBUTE index 7c3421ed75..04d0ab00d2 100644 --- CONTRIBUTE +++ CONTRIBUTE @@ -366,6 +366,24 @@ 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. + +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. + ** GNU ELPA This repository does not contain the Emacs Lisp package archive diff --git admin/MAINTAINERS admin/MAINTAINERS index e87c3e0204..5b8d73cad7 100644 --- admin/MAINTAINERS +++ admin/MAINTAINERS @@ -316,6 +316,43 @@ Modus themes doc/misc/modus-themes.org etc/themes/modus*.el +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. + + lisp/org/*.el + etc/org/* + etc/refcards/orgcard.tex + doc/misc/org.org + doc/misc/org-setup.org + doc/misc/org.texi + ;;; Local Variables: ;;; coding: utf-8 -- 2.34.1 --=-=-=--