On 8/1/19 4:01 PM, Jakub Jelinek wrote:
> You can easily tweak the script to handle the other way too.
> Looking around, different people have different style, some people don't
> post the date/name/email lines at all, others do, some people post them
> multiple times, once for each ChangeLog, others just once, and for the
> latter case, some people post gcc/, etc. prefixes before the entries
> afterwards, while others don't, and others do it only conditionally
> (e.g. when the number of ChangeLog files is too high or it isn't immediately
> obvious which ones they are for, say one entry for gcc and one for
> gcc/testsuite ChangeLog, or similarly for gcc/cp and gcc/testsuite etc.
> isn't hard to figure out and is just noise.
> So, either we have multiple options for mklog, so that people if they prefer
> some other style don't have to rewrite it all the time, or have one style we
> want to recommend. If the latter, I think it is better to have a style that
> is perhaps automatically parseable by a script, on the other side for
> readers of the mailing list should minimize unnecessary cruft and
> redundancies. For that I think the email line just once, then empty line,
> then PR lines and/or line with short summary as some people use, then
> the dirnames of ChangeLog entries (but no ChangeLog, that is always the
> case) and actual entries sounds best to me.
Let me share my 2c -- the format GDB uses doesn't affect most GCC forks
of course, though uniformity across GNU tools is a good thing to have
in my opinion, to ease sharing tooling and ease moving between projects.
"email just once" assumes that you have a single author or set of authors
for the whole patch. But if you have a patch that includes entries by
different authors, then you have to have multiple ChangeLog "blocks" each
with its author/email line, ending up where you didn't want to to begin
with, anyway, like:
YYYY-MM-DD John Doe <j...@doe.com>
gcc/
* ...
YYYY-MM-DD Joe Shmoe <j...@shmoe.com>
gcc/testsuite/
* ...
With the "email line per ChangeLog file entry" style, there's
no exception to the rule, it all just always looks the same, like:
gcc/
YYYY-MM-DD John Doe <j...@doe.com>
* ...
gcc/testsuite/
YYYY-MM-DD Joe Shmoe <j...@shmoe.com>
* ...
This isn't your everyday patch, of course, but it does
show up here and there.
IMHO, saving a few characters/bytes doesn't justify the simplicity
of just having a full entry per ChangeLog file.
FWIW, this is the style used by GDB, as documented at the end
of section 9, at
<https://sourceware.org/gdb/wiki/ContributionChecklist#Properly_Formatted_GNU_ChangeLog>.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"In your patch email you should also specify which changelog is being modified.
Before the line containing the date and your name/email, add a line with the
path to the changelog. If there are multiple components being updated with
multiple changelog edits, split these into sections, one for each changelog:
gdb/ChangeLog:
2013-12-12 John Doe <johndoe@some.email.address>
PR gdb/9999
* breakpoint.c (handle_some_event): Remove reference to foo. Call
bar.
* configure.ac (build_warnings): Do not use -Wformat-nonliteral
with -Wno-format.
* configure: Regenerate.
* NEWS: Mention awesome feature.
gdb/testsuite/ChangeLog:
2013-12-12 John Doe <johndoe@some.email.address>
PR gdb/9999
* Makefile: Test changes for awesome feature.
"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pedro Alves
