[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: File names in ChangeLog entries
From: |
Eli Zaretskii |
Subject: |
Re: File names in ChangeLog entries |
Date: |
Thu, 02 Dec 2021 09:12:25 +0200 |
> 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).
- Re: File names in ChangeLog entries, (continued)
- Re: File names in ChangeLog entries, Stefan Monnier, 2021/12/02
- Re: File names in ChangeLog entries, Juri Linkov, 2021/12/02
- Re: File names in ChangeLog entries, Eli Zaretskii, 2021/12/02
- Re: File names in ChangeLog entries, Stefan Monnier, 2021/12/02
- Re: File names in ChangeLog entries, Eli Zaretskii, 2021/12/03
- Re: File names in ChangeLog entries, Stefan Monnier, 2021/12/03
- Re: File names in ChangeLog entries, Eli Zaretskii, 2021/12/03
- Re: File names in ChangeLog entries, Karl Fogel, 2021/12/02
- Re: File names in ChangeLog entries, Stefan Kangas, 2021/12/02
- Re: File names in ChangeLog entries, Karl Fogel, 2021/12/02
- Re: File names in ChangeLog entries,
Eli Zaretskii <=
- Re: File names in ChangeLog entries, Stefan Monnier, 2021/12/02
- Re: File names in ChangeLog entries, Eli Zaretskii, 2021/12/02
- Re: File names in ChangeLog entries, Eli Zaretskii, 2021/12/02
- Re: File names in ChangeLog entries, Matt Armstrong, 2021/12/02