Re: Using the vcs_to_changelog.py script

[Simon Marchi <simon.marchi@polymtl.ca>]

On 2020-02-14 4:45 a.m., Eli Zaretskii wrote:
>> Cc: binutils@sourceware.org, gdb-patches@sourceware.org
>> From: Simon Marchi <simon.marchi@polymtl.ca>
>> Date: Thu, 13 Feb 2020 16:07:14 -0500
>>
>> On 2020-02-13 1:58 p.m., Eli Zaretskii wrote:
>>>   2) we need some guidelines for "good commit messages", otherwise
>>>      patch review will need to pay a lot of attention to discussing
>>>      that and making sure the log messages are fine
>>
>> We can write some guidelines for sure, it wouldn't hurt.  But I think that as a
>> project, we have already some quite good standards in terms of commit messages.
> 
> AFAIU, our current standards assume the ChangeLog-formatted entry is
> part of the log message which describes the individual changes.  If
> that is removed, we may wish to modify our standards to make up for
> the loss.

Do you know where that is written?
> 
> E.g., compare the 2 sample log messages below.  The first one will
> probably be quite incomplete if the ChangeLog part is removed, while
> the second will probably not suffer too much.  So we may wish to make
> sure log messages like the first one are augmented by additional
> information.
> 
>   commit 66182876b46d40163e81504f7fa4f206268cb83c
>   Author:     Eli Zaretskii <eliz@gnu.org>
>   AuthorDate: Mon Jan 6 21:54:21 2020 +0200
>   Commit:     Eli Zaretskii <eliz@gnu.org>
>   CommitDate: Mon Jan 6 21:54:21 2020 +0200
> 
>       Fix MinGW native compilation of gdb/gdbsupport/gdb_wait.c
> 
>       gdb/ChangeLog
>       2020-01-06  Eli Zaretskii  <eliz@gnu.org>
> 
> 	      * gdbsupport/gdb_wait.c: Include <signal.h> instead of
> 	      gdb/signals.h, as we are now using native signal symbols.

Well, you would essentially just say the same thing, just not in "ChangeLog
entry" format.  I'm not sure what's the problem here.

Note that if I were to review this patch, I would probably ask for a bit more
context in the commit log though (on top of what you already say in the
ChangeLog entry).  I'm sure there was a big discussion that lead to this change,
so from your point of view, this change probably seemed obvious.  But as
somebody lacking the relevant context, I can't really tell why including
gdb/signals.h was wrong and why including signal.h is better.

I would therefore suggest adding:

- What's the problem you're trying to fix (compilation error?  if so please
  paste it in the commit log?)
- Why is this the right way to fix it?

Simon