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 03:06:11 -0600 Message-ID: <87bl0kgdto.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> <87czl0j7vf.fsf@gmx.de> 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="35365"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Kyle Meyer , emacs-devel@gnu.org To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Jan 10 10:08:15 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 1n6qf0-000918-PJ for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 10:08:15 +0100 Original-Received: from localhost ([::1]:42282 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n6qez-0002jf-Ds for ged-emacs-devel@m.gmane-mx.org; Mon, 10 Jan 2022 04:08:13 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:52820) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6qd5-0000Mu-RT for emacs-devel@gnu.org; Mon, 10 Jan 2022 04:06:16 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:35796) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6qd3-0001Et-QF for emacs-devel@gnu.org; Mon, 10 Jan 2022 04:06:15 -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=+3QvllQZjPBNEIHAyrB4f8q22+YgU2biCw4IUrX7qLQ=; t=1641805573; x=1643015173; b=SovX0fqFgKwYSMcqSXhQaeEniwDVcPWnPYvuaoTuVxpq14VMmYJXWrVW+XV373Jqh/e8o+24b9K atmOgWjch807aidQ6HQ2hzOi4O133VXdE7a9FwNBgHlyN0jtq1sJ5gNtAEg8l12S3UyX5oYQoXtQe mj69VUglPK/2/TAM2qF+K9J49xSzxaGVzPlDUBxWLG2Ytzdh9ilzDdQcCHCyF2pIYDXDH75NTDWgb 3EfdSxLcuJQS7E1wZoxpSSC50JcTxK9ypkvMqo2jsk7XMnX4R+xWnMN2BiMdj2slC3+OYYMDztC70 dbBlECpq/85bnphKwEFwm3m0Se02kP+wKfTw==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60516 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 1n6qd1-001Hct-29; Mon, 10 Jan 2022 09:06:11 +0000 In-Reply-To: <87czl0j7vf.fsf@gmx.de> (Michael Albinus's message of "Mon, 10 Jan 2022 09:46:28 +0100") 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:284524 Archived-At: On 10 Jan 2022, Michael Albinus wrote: >> * 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. > >That's OK. Org-mode has a lot of own test files not integrated >into >Emacs repo; I hope we can get them too. I hope so too. However, for our purposes here, we don't care about files on the Org Mode side that aren't currently integrated into Emacs's repository; we only care about what's present in Emacs. >> +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. > >I'm not sure that this is always the case. For Tramp, I'm happy >if >people refer to the Emacs repo files; sync with the upstream >package is >something contributors don't need to worry about. We shall keep >the >barrier low. Hmmm. In that case, should Tramp be listed in the "Externally maintained packages" section of admin/MAINTAINERS at all? The purpose of that section, and of the new material in CONTRIBUTE, is to make contributors be aware of the situations in which they *do* need to pay attention to the fact of external maintenance -- that is, situations in which contributors might need to do something differently from how one would normally do it. In situations where they can just send their contribution to Emacs in the usual Emacs-y way, then there is no need for special documentation in the first place. We could change "often" to "sometimes" in the above-quoted text, but I think it's worth asking if Tramp should even be listed, if Tramp is happy to receive contributions via the usual Emacs project route anyway. >More important are compatibility restrictions. All of these >externally >maintained packages have their policy, we shall advice potential >contributors to respect them. Refer to the respective >Package-Requires: >header line. > >> +Org Mode >> + Home Page: https://orgmode.org/ >> + Maintainer: Org Mode developers > >The sync between org-mode and Emacs is performed by Kyle Meyer >, shall we mention him as the guy to be >contacted in >case of? IMHO Emacs should avoid duplicating documentation that's available from the upstream projects themselves. We should just send people upstream to get the latest information, whether about compatibility guidelines or anything else. In fact, I wasn't even sure about listing the Org Mode version control repository explicitly in the section I added; I only did it for consistency with the other similar sections. Ideally, the contributor should just go look at orgmode.org (or whatever the appropriate upstream landing page is, for other packages) and follow the pointers there. The reason I added the long note in the Org Mode section is that Org Mode's situation is unusually complex, and AFAIK it's not summarized like that -- i.e., from the GNU Emacs development point of view -- on Org Mode's own site. Best regards, -Karl