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: File names in ChangeLog entries Date: Thu, 02 Dec 2021 00:43:35 -0600 Message-ID: <87wnknpkvc.fsf@red-bean.com> References: <831r2xt32t.fsf@gnu.org> <83ilw8sa9j.fsf@gnu.org> <835ys8s1gg.fsf@gnu.org> <87czmgruyc.fsf@gnuvola.org> <83h7bsqfxh.fsf@gnu.org> Reply-To: Karl Fogel Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="16513"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Eli Zaretskii , emacs-devel@gnu.org, Stefan Monnier , Thien-Thi Nguyen To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Dec 02 07:50:03 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 1msfur-00040H-4H for ged-emacs-devel@m.gmane-mx.org; Thu, 02 Dec 2021 07:50:01 +0100 Original-Received: from localhost ([::1]:39076 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1msfup-0002KP-0D for ged-emacs-devel@m.gmane-mx.org; Thu, 02 Dec 2021 01:49:59 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:33966) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1msfp6-0007iz-B3 for emacs-devel@gnu.org; Thu, 02 Dec 2021 01:44:08 -0500 Original-Received: from sanpietro.red-bean.com ([45.79.25.59]:36896) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1msfom-0001xw-Gk; Thu, 02 Dec 2021 01:44:02 -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=2O83MUjhmKsifBXxL52Gt/GIs8WbZvxkMJFUclrxwQM=; t=1638427419; x=1639637019; b=SvE/Mr9zf+2gyTE+S+SivBl9anNVmCULr+knZ+jqZcL2P9+p9/MzLp2dZAI7p7cyVr2iFXI9enJ dFYwdxBdYn8/uw9eUpeiznS9W44o7Dm9WO2Mc1bHxdPUZVF6goqFuXk7RnhfJmIgKD7hnjmpCqQWx 1ouhtO7rwKnn4omo5QU/TkmCcfl+un6Tm1inZEXcgxHKfJFP9uugParH0fdv6Xl83IM756uHIBeZj acJnvtHZcpjIt7QV13ve5g9RLrsxRK4dR4OjHJLldQeHUs2vOty7lnLwNF0VwHKip9BtlZdPNQDMU EoDZYq0W+r72YRuF1RB5VJHpcYbUyg6//HCg==; Original-Received: from 99-112-125-163.lightspeed.cicril.sbcglobal.net ([99.112.125.163]:60206 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 1msfoe-0071lS-Sj; Thu, 02 Dec 2021 06:43:36 +0000 In-Reply-To: (Stefan Kangas's message of "Wed, 1 Dec 2021 15:14:05 -0800") 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:280713 Archived-At: --=-=-= Content-Type: text/plain; format=flowed On 01 Dec 2021, Stefan Kangas wrote: >Stefan Monnier writes: > >> As for the " (func)" I only put it there if there's room. > >In cases where mentioning the function is particularly important, >I'd >rather say > > function-name: Short description > >Given that we prefer to include package prefixes in our symbols, >it >should also tell you something about where the function can be >found. >In many cases, at least. > >But as you say, it is hard to find hard rules, and some >creativity will >inevitably be needed. The main point, though, is the one you yourself made earlier: There is a good reason to keep that first summary line as short as possible. Git often prints it prefixed by other information, in such a way that the summary line gets crammed against the right edge -- so if it's too long, it may wrap awkwardly or go off the screen. You gave "git log --format=short" as an example, but an even more common situation in my experience is "git show-branch". I'll attach some output from that command to this email (as an actual text/plain attachment, to make absolutely sure the formatting is preserved, since the formatting is important here). If one looks at that output, one can see right away why having reliably short summary first-lines in the commit messages is useful. Many free software projects have adopted a "50 characters, with no trailing dot" rule for that first line, to the point where programmers often treat it as a standard. (When we onboard new programmers at our company, for example, I find that they generally already know about this rule and expect us to be following it, which we are.) Emacs doesn't have to do things the way those other projects do, but I hope the above helps clarify why we might want to be more consistent about doing it that way. Our CONTRIBUTE file does already say that 50 chars for the summary line is "nicer". (Although it gives that advice two points down from where we first mention the summary line, which is odd. I've attached a patch here that tries to improve this, and would appreciate others' review.) Best regards, -Karl --=-=-= Content-Type: text/plain Content-Disposition: attachment; filename=SAMPLE-OUTPUT-git-show-branch.txt Content-Description: 'git show-branch' sample output $ git show-branch master emacs-28 * [master] * lisp/cedet/semantic/bovine/c.el (semantic-tag-protection): Silence warning ! [emacs-28] ; Update loaddefs files. -- * [master] * lisp/cedet/semantic/bovine/c.el (semantic-tag-protection): Silence warning * [master^] * lisp/emacs-lisp/macroexp.el: Improve last change * [master~2] Add some primitive momentum-based precision scrolling * [master~3] Add `touch-end' event type * [master~37] Add an ldefs-boot.el target to the Makefile ... * [master~1208] Save position in mark ring before jumping to definition * [master~1209] Update emacs-module sources for Emacs 29 * [master~1210] Bump Emacs version to 29.0.50 + [emacs-28] ; Update loaddefs files. + [emacs-28^] ; make change-history-commit + [emacs-28~2] * lisp/repeat.el: Use same logic for repeat-check-key and repeat-exit-timeout. ... + [emacs-28~11] CC Mode: Recognise "struct foo {" as introducing a type declaration *+ [emacs-28~12] ; Auto-commit of loaddefs files. $ --=-=-= Content-Type: text/plain Content-Disposition: attachment; filename=PATCH-improve-commit-messages-documentation.txt Content-Description: PATCH: Improve CONTRIBUTE's documentation of commit messages diff --git CONTRIBUTE CONTRIBUTE index 5740004637..7c3421ed75 100644 --- CONTRIBUTE +++ CONTRIBUTE @@ -185,20 +185,26 @@ ChangeLog file, where they can be corrected. It saves time to get them right the first time, so here are guidelines for formatting them: - Start with a single unindented summary line explaining the change; - do not end this line with a period. If that line starts with a - semicolon and a space "; ", the commit message will be ignored when - generating the ChangeLog file. Use this for minor commits that do - not need separate ChangeLog entries, such as changes in etc/NEWS. + do not end this line with a period. If possible, try to keep the + summary line to 50 characters or fewer; this is for compatibility + with certain Git commands that print that line in width-constrained + contexts. -- After the summary line, there should be an empty line, then - unindented ChangeLog entries. + If the summary line starts with a semicolon and a space "; ", the + commit message will be ignored when generating the ChangeLog file. + Use this for minor commits that do not need separate ChangeLog + entries, such as changes in etc/NEWS. + +- After the summary line, there should be an empty line. + +- Unindented ChangeLog entries normally come next. However, if the + commit couldn't be properly summarized in the brief summary line, + you can put a paragraph (after the empty line and before the + individual ChangeLog entries) that further describes the commit. - Limit lines in commit messages to 78 characters, unless they consist of a single word of at most 140 characters; this is enforced by a - commit hook. It's nicer to limit the summary line to 50 characters; - this isn't enforced. If the change can't be summarized so briefly, - add a paragraph after the empty line and before the individual file - descriptions. + commit hook. - If only a single file is changed, the summary line can be the normal file first line (starting with the asterisk). Then there is no --=-=-=--