Re: Rant about ChangeLog entries and commit messages

[Robert Kiesling <kiesling at earthlink dot net>]

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

One line of reference would be sufficient provided that branches other
than the main development trunk stick to revisions in that branch only.
I haven't glanced through the references yet, but maintenance programming
is considerably different than writing new code, or even modifying 
someone else's code.  If it's the latter you're trying to achieve, or 
anticipate achieving, then an accurate line of reference would be most 
helpful.  

Unfortunately, then, _someone_ has to maintain the comments accurately.
I wouldn't care to say who (whom?)... just... someone.  :)

-- 
Ctalk Home Page: http://ctalk-lang.sourceforge.net