Re: Rant about ChangeLog entries and commit messages

[tim <tejgcc at westnet dot com dot au>]

On Sun, 2007-12-02 at 09:26 -0500, Robert Kiesling wrote: 
> > I guess nobody really loves writing ChangeLog entries, but in my opinion there 
> > are quite effective "executive summaries" for the patches and helpful to the 
> > reader/reviewer.  Please let's not throw the baby with the bath's water.
> 
> If there's a mechanism to filter checkin messages to ChangeLog summaries, 
> I would be happy to use it - in cases of multiple packages, especially, it's 
> important to know what changes were made, when, and when the changes propagated
> through packages and releases, and where they got to, occasionally.  Anybody
> know of a useful, built-in mechanism for this task?
> 

Personally I find it slow and inefficient tracing through why a given
change was made. It is just a slow process searching and sometimes I
don't bother because it is so inconvenient. The ChangeLog entries
provide little help and there does not seem to be a good alternative. If
there is a good alternative no-one has said what it is so far.

As people have pointed out, the RCSs pretty well cover the "what" these
days. And writing changelog entries, which largely duplicate this
information, is time-consuming and tedious. And there are of of little
to no value to me at least.

The coding standards do allow, in some cases, that giving some context
would be useful:

> See also what the GNU Coding Standards have to say about what goes in
> ChangeLogs; in particular, descriptions of the purpose of code and
> changes should go in comments rather than the ChangeLog, though a
> single line overall description of the changes may be useful above the
> ChangeLog entry for a large batch of changes.

I personally would strongly favour each ChangeLog entry having a single
line of context. This could be the PR number or a single line giving the
purpose of the change or what bigger change it is part of. 

As pointed out by Zach Weinberg in his paper "A Maintenance Programmer's
View of GCC", there are many impediments to contributing to GCC.

http://www.linux.org.uk/~ajh/gcc/gccsummit-2003-proceedings.pdf

Things are not much better than they were when Zach wrote his paper. This small change would be one positive step n the right direction, IMHO.

Tim Josling