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, 02 Jan 2022 23:05:05 -0600 Message-ID: <87fsq5tnni.fsf@red-bean.com> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.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="24683"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Eli Zaretskii To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jan 03 06:07:44 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 1n4FZP-0006D6-62 for ged-emacs-devel@m.gmane-mx.org; Mon, 03 Jan 2022 06:07:43 +0100 Original-Received: from localhost ([::1]:39244 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n4FZN-0002wz-C9 for ged-emacs-devel@m.gmane-mx.org; Mon, 03 Jan 2022 00:07:41 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:43224) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4FWy-00024V-MK for emacs-devel@gnu.org; Mon, 03 Jan 2022 00:05:13 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:45988) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4FWw-000187-Lk; Mon, 03 Jan 2022 00:05:12 -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:Cc:To:From:Sender: Content-Transfer-Encoding:Content-ID:Content-Description; bh=qSWn7UBwfzKj+GZHG7Cd+IGfkrckJZm3/PIqNWmpGm8=; t=1641186308; x=1642395908; b=ci8eZOWTCNdWQxifDFMaiIK3cjKXPD6dsDPdWbAv02L4PwT4DiqoqdF78PACHzaLa8TFaL1KZ0A NbxCoWUdn0drYiyrj5s+QwDgF5dCpsx9OpKIb2DoOQCUMQc7Jl4RHhSnCKl4xQvQwtM7RCktZJOEr NF0ZLMsd/enQaBt8yhIoI2q3lkcBycpww9Tp2ADet2yOvIAkbhewlZsOhcG08DwBGAHB+Po/tI7Qs LXp21OZX9p7JbnSKEMehWyKnfjbCXZePPI180GlxRB7kRZEqhOlTjIvdYqC6kRM/bX42TjQCJxii5 xPqU9HAtpSz1OMIY+XgZYJOJbLD8AvTLVy6Q==; Original-Received: from d-162-218-18-129.wv.cpe.atlanticbb.net ([162.218.18.129]:49198 helo=klen) 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 1n4FWt-00EzgP-EM; Mon, 03 Jan 2022 05:05:07 +0000 In-Reply-To: <834k7n5zfu.fsf@gnu.org> (Eli Zaretskii's message of "Sun, 05 Dec 2021 08:38:13 +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: -1 X-Spam_score: -0.2 X-Spam_bar: / X-Spam_report: (-0.2 / 5.0 requ) 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=unavailable 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:283996 Archived-At: --=-=-= Content-Type: text/plain; format=flowed On 05 Dec 2021, Eli Zaretskii wrote: >> I'd like to improve our in-tree documentation of how Org Mode >> integration into GNU Emacs works. > >Thanks. Can you provide a rough sketch, in the form of list of >items, >of what you'd like to document, and who would be the main >audience for >that? I don't have a clear idea of that based on what you >posted. Sure. (The attached patch may answer your questions more efficiently, though.) * Audience: The audience is Emacs developers and potential developers who are tracking down bugs, or trying to contribute enhancements, but who don't know that certain packages (such as Org Mode) are externally maintained. It's better for us all if such a person finds out as soon as possible where the active upstream for a package is. For example, if they've found a bug in Org Mode, they should take the bug report to the Org Mode forums and discuss it with the Org Mode maintainers. (Maybe sometimes Emacs Devel should also be involved, but the person should at least start out in the proper upstream forum and then be guided appropriately from there.) * List of items: All the packages that ship as part of Emacs but that are externally maintained. Right now, Org Mode is the only one I know of, but I suspect there are others. If people would like to point others out to me, I'll update the attached patch to include them too. The attached patch is an attempt to document this situation in such a way that developers are likely to encounter the documentation when they most need it. Comments welcome; I'm certainly open to other strategies. 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 b709de6a9ffb4cbb30b480f97f1de009a00769a9 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 Org Mode's provenance specifically. 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 | 17 +++++++++++++++++ lisp/org/README | 6 ++++++ 2 files changed, 23 insertions(+) create mode 100644 lisp/org/README diff --git CONTRIBUTE CONTRIBUTE index 7c3421ed75..6f3bb9bf32 100644 --- CONTRIBUTE +++ CONTRIBUTE @@ -366,6 +366,23 @@ 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 actually +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. + +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. + +Note that not all the independently-maintained packages in Emacs have +such a "README" yet. If you know of one that's missing its "README", +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..f9fe1e6edc --- /dev/null +++ lisp/org/README @@ -0,0 +1,6 @@ +Org Mode is maintained as a separate project, and is periodically +merged into Emacs. + +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. -- 2.34.1 --=-=-=--