Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu <sam@rfc1149.net>]

On  2/12, Eric Botcazou wrote:

| He indeed cannot, but the ChangeLog is not meant to make it possible either.
| See http://gcc.gnu.org/contribute.html, especially the GNU Coding Standards.

I know this document and I think the part on ChangeLog doesn't achieve
its purpose:

http://www.gnu.org/prep/standards/standards.html#Change-Logs

   Keep a change log to describe all the changes made to program source
   files. The purpose of this is so that people investigating bugs in the
   future will know about the changes that might have introduced the bug.
   Often a new bug can be found by looking at what was recently changed.
   More importantly, change logs can help you eliminate conceptual
   inconsistencies between different parts of a program, by giving you a
   history of how the conflicting concepts arose and who they came from.

This is precisely why I am proposing an evolution in the current
process.

Also, this document states:

   There's no need to describe the full purpose of the changes or how
   they work together. If you think that a change calls for explanation,
   you're probably right. Please do explain it—but please put the
   explanation in comments in the code, where people will see it whenever
   they see the code.

When you fix a bug by changing a constant (for example if there has been
an offset by one error or, as I did a few minutes ago in
config/sh/sh.md, there was an error in the argument to consider), this
doesn't always mandate a comment in the code. For example, I think a
description such as the one I wrote when describing the problem

   cmpgeusi_t splitting code compares operand 0 to 0, while this constant
   value can only be in operand 1. When compiling the Ada runtime, this
   leads to a "cmp/hs #0,r7" instruction which is not valid as "cmp/hs"
   operands must be two registers.

along with the above change would have been a better commit message than
just

    gcc/
        * config/sh/sh.md (cmpgeusi_t): Fix condition.

which I used as suggested.

| That's how it has always worked so it should be more or less practical.

Sure, it works. But this is not a reason not to improve the process.

| For PRs, there is a link (URL: field), maybe we should use PRs more often.

This field is useful to look at the discussion that led to the change,
but PRs often contain no synthetic information on the analysis of the
problem unless when the PR submitter sends a patch himself (in which
case he often includes his analysis to get a better chance to get his
patch checked in).