Re: File names in ChangeLog entries

[Stefan Monnier <monnier@iro.umontreal.ca>]

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

Indeed, it seems redundant to mention the file name afterwards since
it's the only file affected and it's already mentioned in the summary.
But I'm fine with adding the repetition here.

>     * 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".

Yes, this is a hybrid between the old

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

and the new summary+explanation+changelog format where I tried to be
clever since the `subr-x` part is the core one and the other ones are
just minor sidekicks.
I'm fine with avoiding such cleverness.

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

Not sure what I was smoking back then, indeed.

> due to your self-imposed conventions: there's no need to state the
> full file name, with leading directories, on the summary line.

Agreed.  I just need/want *some* information about which files
are affected.  `ruby-mode` or `subr-x` would be perfectly fine for that.

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

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

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

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

But I can accommodate a convention where the file names are always
clearly spelled out in the "bottom changelog section", even if that's
redundant with the info in the summary line, for the benefit of
generating those legacy files.

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?


        Stefan