Re: File names in ChangeLog entries

[Karl Fogel]

On 02 Dec 2021, Eli Zaretskii wrote:
> > From: Juri Linkov <juri@linkov.net>
> > Cc: Stefan Kangas <stefan@marxist.se>,  Eli Zaretskii 
> > <eliz@gnu.org>,
> >   emacs-devel@gnu.org,  Stefan Monnier 
> >   <monnier@iro.umontreal.ca>,
> >   Thien-Thi Nguyen <ttn@gnuvola.org>
> > Date: Thu, 02 Dec 2021 11:12:05 +0200
> >
> > > *  [master~1208] Save position in mark ring before jumping to 
> > > definition
> >
> > This is a good example of an unhelpful commit message.
> > There is no way to guess it's about lisp/help-mode.el.
>
> You don't need to guess, you need to look at the rest of the log
> message.  We cannot realistically require that everything about 
> the
> change will be clear from the summary.  Mentioning file names is, 
> IME,
> mostly a waste there, because the file name provides very little
> information about the change itself, and takes quite a lot of 
> space,
> so doesn't allow to say enough about the change.

Agreed.

The point of the summary line is to encapsulate some recognizable 
core thing about the change.  When you're reading over, say, a 
long vertical list of such summaries, you can quickly recognize 
ones you already had some awareness of (and this makes branch 
comparison much easier).

We'll never be able to fit *everything* in a summary line, and 
there's no need to.  If one needs further information about that 
particular change, one can go look at the full message.

Best regards,
-Karl