From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Improving documentation of Org Mode integration into Emacs. Date: Mon, 10 Jan 2022 20:14:32 +0200 Message-ID: <83tueb8nlj.fsf@gnu.org> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.fsf@gnu.org> <87fsq5tnni.fsf@red-bean.com> <87ee5mlvyc.fsf@red-bean.com> <83lezu9tv1.fsf@gnu.org> <87zgo4v8rb.fsf@red-bean.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="11460"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Karl Fogel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jan 10 19:19:07 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 1n6zG6-0002lU-Mw for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 19:19:06 +0100 Original-Received: from localhost ([::1]:46724 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n6zG5-00050Z-OW for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 13:19:05 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:54958) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6zBq-0006f1-AT for emacs-devel@gnu.org; Mon, 10 Jan 2022 13:14:42 -0500 Original-Received: from [2001:470:142:3::e] (port=52966 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6zBp-00022r-QS; Mon, 10 Jan 2022 13:14:41 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=UciTAwjo29yg6QZqggyXOEPAdG/Th953VdOrCMkKLto=; b=VmwVa3CE7xJq 4C/HY68dy19aLu0r8m/W6MMocCbwUOL6FubrvfxQqaAm7dsoaxzaThkM6BfNQVb45Kvs4qe1iCxvP cME9+CAGmUFomYLILn+EUtAlumr82y95yEXp3Unzg0xy+HOeq8nmtnpm5w5Gc4KcoZqkQoPK62N86 AbIaIQ0JYzePZda2HgKdjJQBFCJ0RTIdVr+nfVXQTxDbrJouvHOHYKxEvk/JvqAJs3wE8wTuCcl2H KXJGghYvW9QV55EVHcVc1Mj/cgFyxc41Qpkac95rnNRV/mjsVwvnYx6TUwQCIMNTiQ3Aix57j7d52 M+xKeLv0zd+L+sGtiUooIw==; Original-Received: from [87.69.77.57] (port=1653 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6zBp-0008IK-SF; Mon, 10 Jan 2022 13:14:42 -0500 In-Reply-To: <87zgo4v8rb.fsf@red-bean.com> (message from Karl Fogel on Sun, 09 Jan 2022 16:34:16 -0600) 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:284544 Archived-At: > From: Karl Fogel > Date: Sun, 09 Jan 2022 16:34:16 -0600 > > --- 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. This is okay, but I'd lose the last sentence: it isn't different from saying "if you see something wrong in Emacs, please submit a patch". > +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. I'd lose the two last paragraphs. They are not really needed for people to report issues with Org. If/when someone becomes intimately involved with Org development, they will learn those aspects; but it is not the job of CONTRIBUTE or MAINTAINERS to teach them that. Thanks.