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: Wed, 05 Jan 2022 15:48:02 +0200 Message-ID: <83lezu9tv1.fsf@gnu.org> References: <87zgpgax7w.fsf@red-bean.com> <834k7n5zfu.fsf@gnu.org> <87fsq5tnni.fsf@red-bean.com> <87ee5mlvyc.fsf@red-bean.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="19053"; 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 Wed Jan 05 14:48:51 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 1n56eo-0004kd-Gp for ged-emacs-devel@m.gmane-mx.org; Wed, 05 Jan 2022 14:48:50 +0100 Original-Received: from localhost ([::1]:41186 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n56en-0006kO-3Z for ged-emacs-devel@m.gmane-mx.org; Wed, 05 Jan 2022 08:48:49 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:48676) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n56dt-00058F-F8 for emacs-devel@gnu.org; Wed, 05 Jan 2022 08:47:53 -0500 Original-Received: from [2001:470:142:3::e] (port=42692 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 1n56ds-0003bb-Rr; Wed, 05 Jan 2022 08:47:52 -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=vq2VqWHFygPHI6vfHkV5yIMfe+7MUWAFpT4+k60ApsU=; b=JQcNmJUa16l2 zGsKToBZzT5P3X3ZCFLyT8EyU5P+9u2+4aIEdXPuWNHLYGuIQURODGB1YlSEVMX0VxZdgjm9yxef2 AkfMhVNLvnMXe+bPCPpE/SrjVOJylKz0Cnb2MsT3tLMwfRBtSK9/+TPaVFWZEgNkrQHC/tF76CXba KksUXyUwb4byElEj6wakIZuDofMMaonGkjGWxLpU1qp6MirJ8oIQP/GKaFyEKolLTU0EM56o66uh/ uqY5JjL/acVg2tOayhLjTwd6Pcgiu8rnu5ARloUNrleuPLrG4MB6myp1obvyVvLl5BS7hP2HL9j2O XNg7JVSEhh4r0b155AVqgw==; Original-Received: from [87.69.77.57] (port=3456 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 1n56ds-00058z-RV; Wed, 05 Jan 2022 08:47:53 -0500 In-Reply-To: <87ee5mlvyc.fsf@red-bean.com> (message from Karl Fogel on Tue, 04 Jan 2022 21:09:47 -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:284240 Archived-At: > From: Karl Fogel > Date: Tue, 04 Jan 2022 21:09:47 -0600 > > On 03 Jan 2022, Eli Zaretskii wrote: > >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. > > The attached (revised) patch gives some specific instructions as > examples. I don't think providing just examples is the best idea. See below. > But CONTRIBUTE's job is just to explain the general > situation about externally maintained packages and give a few > examples, so that developers understand why they need to be watch > out for this situation. I think we should explain the issue concisely, and then provide specific instructions. This text is IMO enough for the first part: +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. Following that, we should provide a full, exhaustive list of all such packages in Emacs core, each one with a corresponding URL (mailing list, upstream repository with an issue tracker, etc.). It might be a good idea to have this list on a separate file, perhaps in etc/, and only have CONTRIBUTE point to that file. > But CONTRIBUTE shouldn't give the specific instructions for each > package. It should just show the developer how to figure out if a > package is externally maintained, and then that package can point > the developer in the right direction in whatever way is most > appropriate. I disagree. If we don't provide a full list of such packages with precise instructions, we will not make any significant progress: people would still need to ask us about the details, when they aren't "smart" enough (or patient enough) to read the instructions that teach them how to deduce that by themselves. Moreover, as you have found out already, there's no standard way such packages use to "plug" themselves into Emacs, so it's likely that any general instructions we provide will be inaccurate in some cases. An exhaustive "cookbook" is much better, IMO, and is easier to maintain in the long run. It will also be shorter, which is a nice bonus, given today's "TL;DR" attitude. Thanks.