Re: File names in ChangeLog entries

[Karl Fogel]

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

SAMPLE-OUTPUT-git-show-branch.txt
Description: 'git show-branch' sample output

PATCH-improve-commit-messages-documentation.txt
Description: PATCH: Improve CONTRIBUTE's documentation of commit messages