Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu <sam at rfc1149 dot net>]

On  2/12, Eric Botcazou wrote:

| > 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.
| 
| Could you elaborate?

I'll take an example from one of your recent changes in gcc/ChangeLog:

   2007-11-19  Eric Botcazou  <ebotcazou@adacore.com>

           * stor-layout.c (lang_adjust_rli): Delete.
           (set_lang_adjust_rli): Likewise.
           (layout_type): Do not call lang_adjust_rli hook.
           * tree.h (set_lang_adjust_rli): Delete.

Without digging in the mailing-list archives to see why you made the
change, if something new breaks on a STABS platform I will have no hint
that this change was in any way related to STABS.

If we didn't use ChangeLogs and if commit logs contained the information
you gave on the mailing-list, this would be much easier:

   The compiler has been broken on STABS platform since mapped locations
   were enabled by default.  The Ada front-end is emitting debug info too
   early.  The patch also reorganizes a little the front-end's initialization
   and gets rid of dead code in the process, which in turn enables a further
   cleanup in the middle-end.

Also note that the ChangeLog doesn't give any hint that changes in the
ada directory have been made at the same time, only "svn log" reveals
that. So far for the "The purpose of this is so that people investigating
bugs in the future will know about the changes that might have introduced
the bug." sentence.

I would prefer that information which is deemed necessary for
peer-review when a patch is sent to gcc-patches@ is also included in
GCC log history.

| > [sh.md fix]
|
| Not really in my opinion, it's a trivial fix and totally unrelated to Ada in 
| itself, "Fix typo" or "Fix obvious mistake" would have been just fine too.

Well, I find it useful to know which part of the compiler has exercized
this code path (as obviously there was no test associated with this
optimization) and uncovered the bug, but I agree that this was an obvious
typo fix.