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, 03 Jan 2022 15:31:30 +0200 Message-ID: <83ee5pc5e5.fsf@gnu.org> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.fsf@gnu.org> <87fsq5tnni.fsf@red-bean.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32744"; 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 03 14:32:27 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 1n4NRr-0008LH-74 for ged-emacs-devel@m.gmane-mx.org; Mon, 03 Jan 2022 14:32:27 +0100 Original-Received: from localhost ([::1]:50642 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n4NRq-0007Rp-2T for ged-emacs-devel@m.gmane-mx.org; Mon, 03 Jan 2022 08:32:26 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:51640) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n4NQr-0006R2-TA for emacs-devel@gnu.org; Mon, 03 Jan 2022 08:31:25 -0500 Original-Received: from [2001:470:142:3::e] (port=51366 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 1n4NQr-0002VV-JA; Mon, 03 Jan 2022 08:31:25 -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=Wxo4NVM33m8GW6VpbaUAk5B6xJAccswVSH0LfkwAD8E=; b=JgK17ARz/rh+ Kf2bacqpZYDrAEtIaCSQRaI+VPQRiuHUiADptfqbrACliINP3gQRNo9vVecDC2s9kAKL6PRECVMe3 i8h5sdFdVg6d1XsBqQpuTigYH8pNqg6h+w+bTqnf6KpSNvyQawZqh67xgN4ZuYbKQgvtqrjQcSFMQ mcA8L1zSUzjh5aim4BY+shdQtgyPds/REl+4u2/nBE64HA5aeU7RvXF4VJ0jx8TGdn4diO9Y3Tksq owkADFVD3jqorEGrvlF5lI5u5J3DJm1an0lRnF4Y6RhXQhZUmnOgux2v0rm+kTLhjNGVNFIJfgm5L GCvpXasnYCWDrZk8GGx04g==; Original-Received: from [87.69.77.57] (port=4546 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 1n4NQr-0002qZ-Il; Mon, 03 Jan 2022 08:31:25 -0500 In-Reply-To: <87fsq5tnni.fsf@red-bean.com> (message from Karl Fogel on Sun, 02 Jan 2022 23:05:05 -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:284045 Archived-At: > From: Karl Fogel > Cc: Eli Zaretskii > Date: Sun, 02 Jan 2022 23:05:05 -0600 > > >> 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.) 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. > 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.) 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? > +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.