Re: File names in ChangeLog entries

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Thien-Thi Nguyen <ttn@gnuvola.org>,
>   emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 17:21:57 -0500
> 
>     * filenames: Short description
> 
>     Explanation.
> 
>     * file1 (func1): desc1.
>     (func2): desc2.
>     * file2 (func3): desc3.
> 
> where "filenames" is a summary of the files.

This is okay, and doesn't violate our conventions.  (It does waste
precious space on the summary line to mention the file names, which
IME isn't necessary when the summary is well written.  But that's me.)
My problem is not with the above format, my problem is with log
messages that don't really follow it.  Like this one:

    * test/src/comp-tests.el: Rework last patch

    Move `require`s out of `eval-when-compile` if the functions are called
    at run-time.
    Don't use #' to quote symbols (i.e. at those places where a lambda
    expression couldn't be used).
    Don't pre-load comp-test-45603.el and comp-test-pure.el any more.

    (comp-deftest pure): Use `declare-function` after loading `comp-test-pure.el`
    to silence the byte-compiler.

This doesn't state the file name after the summary.  (Also, the lines
are too long, and will produce ugly ChangeLog entries in the tarball.)

    * lisp/emacs-lisp/subr-x.el (with-memoization): New macro

    Extracted from `cl-generic.el`.

    * lisp/emacs-lisp/cl-generic.el (cl--generic-get-dispatcher)
    (cl--generic-build-combined-method, cl-generic-generalizers): Use it.
    (cl--generic-with-memoization): Delete.

This doesn't mention subr-x.el change in the "main part".

    Change ruby-align-chained-calls indendation

    * lisp/progmodes/ruby-mode.el (ruby-smie-rules): Align with the
    first sibling on the previous line instead of the last (bug#32496).

    That is, before it used to be

    one.two.three
           .four

    and now it is

    one.two.three
       .four

Here, the order is incorrect: the "That is" part should have been
before the "* file (func): Desc" part, not after.

All in all, it looks like you arbitrarily put one of the log entries
on the first line to save repetition.  But some of the repetition is
due to your self-imposed conventions: there's no need to state the
full file name, with leading directories, on the summary line.  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

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

And the main problem with your format is that the produced ChangeLog
is ugly and hard to read, while the format we prefer is carefully
designed to produce reasonably-readable ChangeLogs.  Which was why
Stefan Kangas started this discussion in the first place, AFAIU.

I hope this clarifies why I'm unhappy with your log messages.  And if
this is still not convincing, I don't intend to keep arguing, because
I have very little faith that it will lead anywhere useful.  I just
share the frustration expressed by Stefan Kangas (which in his case
came after he invested a lot of efforts fixing that).