Re: File names in ChangeLog entries

[Karl Fogel <kfogel@red-bean.com>]

[-- Attachment #1: Type: text/plain, Size: 2160 bytes --]

On 01 Dec 2021, Stefan Kangas wrote:
>Stefan Monnier <monnier@iro.umontreal.ca> 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


[-- Attachment #2: 'git show-branch' sample output --]
[-- Type: text/plain, Size: 987 bytes --]

$ 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.
$ 

[-- Attachment #3: PATCH: Improve CONTRIBUTE's documentation of commit messages --]
[-- Type: text/plain, Size: 2038 bytes --]

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