This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] Teach mklog to reference PRs.

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

	* ...

YYYY-MM-DD  Joe Shmoe  <>

	* ...

With the "email line per ChangeLog file entry" style, there's
no exception to the rule, it all just always looks the same, like:

YYYY-MM-DD  John Doe  <>

	* ...

YYYY-MM-DD  Joe Shmoe  <>

	* ...

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

"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:

2013-12-12  John Doe  <>

        PR gdb/9999
        * breakpoint.c (handle_some_event): Remove reference to foo.  Call
        * (build_warnings): Do not use -Wformat-nonliteral
        with -Wno-format.
        * configure: Regenerate.
        * NEWS: Mention awesome feature.

2013-12-12  John Doe  <>

        PR gdb/9999
        * Makefile: Test changes for awesome feature.

Pedro Alves

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]