Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stefan@marxist.se,  ttn@gnuvola.org,  emacs-devel@gnu.org
> Date: Thu, 02 Dec 2021 02:34:32 -0500
> 
> > For
> > example, this summary:
> >
> >     * lisp/emacs-lisp/subr-x.el (with-memoization): New macro
> >
> > could have been more economically written as
> >
> >     New macro 'with-memoization'
> >
> > or, if you insist on mentioning the file, as
> >
> >     New macro 'with-memoization' in subr-x.el
> 
> I'd prefer
> 
>      subr-x (with-memoization): New macro
> 
> which is closer to the rest of our conventions.

Our conventions are for the detailed descriptions of the changes.  the
summary line is supposed to be human-readable free text, not
machine-readable text in rigid format.  What you prefer is not bad,
but it is less readable by humans, IMO.

> Having the subsystem
> info always at the beginning is important to be able to visually scan
> many commits quickly without having to read&parse&understand each and
> every summary text.  It's even more important when several commits in
> a row affect the same subsystem in which case the scanning is made even
> faster when all those commits put the subsystem info at the same place.

Those are your personal goals, due to your particular usage of these
parts of the log messages.  But that's not the only use of them, and
not even the main one.

> > And in this example:
> >
> >     * lisp/emacs-lisp/cl-generic.el: Try and fix bug#49866
> >
> >     (cl-generic-generalizers): Remember the specializers that match
> >     a given value.
> >     (cl--generic-eql-generalizer): Adjust accordingly.
> >
> >     * test/lisp/emacs-lisp/cl-generic-tests.el (cl-generic-test-01-eql):
> >     Add corresponding test.
> >
> > the file name in the summary is entirely redundant, since fixing a bug
> > is not necessarily related to a particular file (as the rest of the
> > log message clearly shows).
> 
> I don't understand what you mean: the patch basically only touches
> `cl-generic.el`.

No, it also changes the test suite.

> Indeed, this discussion is related to the generation of the ChangeLog
> and to the fact that I have completely and totally stopped looking at
> them, so I'm beginning to doubt the usefulness of
> keeping/generating them.  [ I'm curious to know who uses them still.  ]

We had this discussion.  There are enough people who want to have a
usable ChangeLog in several situations.  Therefore we decided to
generate them when a release is tarred.  Restarting this discussion
because the ChangeLog format is not to the liking of some of us sounds
to me like a salami tactics: first we take Manhattan, then we take
Berlin.  Let's instead stick to our decisions.

> Is there a chance that others might be willing to accommodate my request
> to always include some subsystem info in the summary line in return?

I don't know.  For me, it'd be an annoyance: I usually try very hard
to come up with a short but detailed enough summary, which isn't easy
in some cases.  Having to "waste" some of the precious space on some
subsystem info would make this a lot harder.