From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Matt Armstrong Newsgroups: gmane.emacs.devel Subject: Re: File names in ChangeLog entries Date: Thu, 02 Dec 2021 08:59:25 -0800 Message-ID: <87tufr0wpe.fsf@rfc20.org> References: <831r2xt32t.fsf@gnu.org> <83ilw8sa9j.fsf@gnu.org> <835ys8s1gg.fsf@gnu.org> <87czmgruyc.fsf@gnuvola.org> <83h7bsqfxh.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33612"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Thien-Thi Nguyen , emacs-devel@gnu.org To: Stefan Monnier , Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Dec 02 18:02:41 2021 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 1mspTl-0008YD-7k for ged-emacs-devel@m.gmane-mx.org; Thu, 02 Dec 2021 18:02:41 +0100 Original-Received: from localhost ([::1]:52600 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mspTk-0003T9-01 for ged-emacs-devel@m.gmane-mx.org; Thu, 02 Dec 2021 12:02:40 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:60116) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mspQm-0007xp-Bp for emacs-devel@gnu.org; Thu, 02 Dec 2021 11:59:36 -0500 Original-Received: from relay1-d.mail.gandi.net ([217.70.183.193]:45599) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mspQj-0007Xm-Qn; Thu, 02 Dec 2021 11:59:36 -0500 Original-Received: (Authenticated sender: matt@rfc20.org) by relay1-d.mail.gandi.net (Postfix) with ESMTPSA id 69C59240005; Thu, 2 Dec 2021 16:59:29 +0000 (UTC) Original-Received: from matt by naz with local (Exim 4.95) (envelope-from ) id 1mspQb-000TIH-N7; Thu, 02 Dec 2021 08:59:25 -0800 In-Reply-To: Received-SPF: pass client-ip=217.70.183.193; envelope-from=matt@rfc20.org; helo=relay1-d.mail.gandi.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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:280766 Archived-At: Stefan Monnier writes: > For the record the problem for me is the following: I read the > `emacs-diffs` mailing-list but I don't read all the messages. I > filter them based on the Subject, and having some idea of which part > of the code is affected is a crucial information for me to decide > whether I should look at the patch. Stefan, since your use case is reasonable, I wonder if there are approaches not yet discussed that could satisfy it? Point being, we're only discussing one possible approach to satisfying your need, in a way that current guidance to change, asks people to change habbits, and in a way that asks people to include arguably redundant, but also largely mechanically defined, information in their hand written commit messages. So, two ideas: A) Change CONTRIBUTE guidance slightly. Today all we say is "Start with a single unindented summary line explaining the change" but we don't describe what a good explanation is. The current example is "Deactivate shifted region", which answers "what" but not "where". It could just as easily be "Deactivate region in newly selected windows" Point is not to satisfy the letter of what you're asking for, but to suggest that the subject line should answer what the change is doing and, if space available, where it applies. B) Add tooling to generate a succinct "subsystem" description from a git commit. Case in point: the GNU ChangeLog format is bearable today because tooling (partially) supports generating it. Why not look at tooling for this job too? If we could come up with an algorithm that takes a git commit (staged or already commited) and describes the "subsystem" (or subsystems) that are touched, then: - we are forced to clearly describe what the "subsystem" description should look like (so far, "functions/files" is what Stefan's has aked for, but I suspect this guideline quickly breaks down for larger commits). - even if the commit message conventions remain the same, it becomes almost trivial to produce a log of succinct "[subsystem(s)]: [summary line]" descriptions, - and even concievable that the `emacs-diffs` list could use this in its subject lines. - ...or this subsystem description logic could be applied to commits in the past... For what it is worth, I skimmed the most recent 100 or so emacs commit messages and noticed two things: - I could already tell which "subsystem" was touched for most of the commits. - I thought that Lars' subject lines struck a nice balance (for me) between reading like English but also covering the questions of "what" and "where."