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: Mon, 10 Jan 2022 13:08:57 -0600 Message-ID: <87tueb76ie.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> <87zgo4v8rb.fsf@red-bean.com> <83tueb8nlj.fsf@gnu.org> Reply-To: Karl Fogel Mime-Version: 1.0 Content-Type: text/plain; format=flowed Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6872"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jan 10 20:17:05 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 1n70AC-0001Zh-B5 for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 20:17:04 +0100 Original-Received: from localhost ([::1]:45070 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n70A9-0006Px-7U for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 14:17:01 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:42670) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n702i-0008R8-C9 for emacs-devel@gnu.org; Mon, 10 Jan 2022 14:09:20 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:50860) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n702c-0003KU-4U; Mon, 10 Jan 2022 14:09:20 -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=bZ0n14drbN1UnSUwDHx4XV2o4C2bHKUw9mPU4a8M73g=; t=1641841739; x=1643051339; b=h/7klaWRr2fAHZB5qMs5yny/7rAJLArsnxC7w3SjFNwqNiIwgY3QpHhK+ZXx5ThVPiSIeRfRGtl RyL8IbDchjeybi26VCgw4IBogWapj4txPAp9h5kbzvB0vS4JxsveHg84I5M7DTvHW8VgrDvmdVgL/ mlRM6t/oXARMk36lavw/14NpP/6yaC0NM6gPT+cD5ShU6Dir3Ntvy2Ly8ErSmvXNa6wEUl4LX7GWa CpDlmse/VGXchA6+5tYvtvYSkiBcj4INtQu6PwwmSbrNf1dzgkqgbXhGWg2ynnPYfw74AkziYNdtG NWZd9JffTnNcNsgLrm2T7mrS0Tfjr57sD87g==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60544 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 1n702L-001a09-Uy; Mon, 10 Jan 2022 19:08:58 +0000 In-Reply-To: <83tueb8nlj.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 10 Jan 2022 20:14:32 +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:284548 Archived-At: On 10 Jan 2022, Eli Zaretskii wrote: >> +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". Okay. I'll commit with changes as noted previously in this thread and in this email. I may change the wording of the previous sentence above to somehow express the point that the list in admin/MAINTAINERS is not guaranteed to be complete. >> +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. Okay. >> Got it. So it sounds like the "Notes" field should give some >> advice about checking the upstream sources and bug tracker >> first, >> when trying to find out if a bug is already known/addressed. >> And >> if you're happy to accept patches against the sources shipped >> in >> Emacs, even when those sources are slightly out-of-date with >> respect to what you have upstream, then "Notes" can say that >> too. > >IMO, that'd be in the "too much information" department. > >We don't need to say everything there, just enough for the people >to >know how to handle a bug report without wasting their time and >ours. We have different judgement about what type of information to include in these entries, but at this point the differences are small, and probably most contributors will be able to figure things out. I'll eliminate those two paragraphs. Thanks for the review, Eli. Best regards, -Karl