Re: [PATCH] Teach mklog to reference PRs.

[Pedro Alves <palves at redhat dot com>]

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  <john@doe.com>

gcc/
	* ...

YYYY-MM-DD  Joe Shmoe  <joe@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  <john@doe.com>

	* ...

gcc/testsuite/
YYYY-MM-DD  Joe Shmoe  <joe@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