Re: [Groff] ChangeLog entries

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> I'm not very comfortable with your editing of ChangeLog entries `a
> posteriori': The entries should represent the changes to the CVS in a
> chronological order.  It's OK for me to edit the entries so that the
> changes of a day or so are properly accumulated (since you tend to
> handle CVS similar to, say, git -- this is, committing changes as fast
> as possible).

It's not that I like to commit "as fast" as possible, it's that I like 
to do fine-grained commits with tests at each step, so that if I screw up
I can always revert to a known-good state without losing much work.

>              However, the idea of the ChangeLog file is that a user
> can look up the changes in a few years by simply comparing the
> differences of two date stamps.  At least this is my point of view.
> 
> My normal approach is to document the changes I've done as a ChangeLog
> entry; then, while committing, I simply reuse the ChangeLog entry for
> the commitment's message.  Of course, this should only be done for
> changes which actually deserve a ChangeLog entry.

The approach I have breen taking was predicated on the assumption that the
ChangeLog entries would be read in conjunction with the CVS history -- so
the latter says "what" and the ChangeLog says "why" at a slightly higher
level.  

But I'm not attached to doing things this way, and will cheerfully attempt 
to conform to your project style.  Do let me know if I emulate it poorly.

While we're on the subject, though, I must say that I think traditional
GNU-style Changelogs are obsolete and irritating.  It's a convention that 
made a lot of sense before use of VCSes became common, but nowadays my
Changelog is normally my VCS commit-message trail.  

I'll update Changelogs (including groff's) because it's good
citizenship -- but I really think they ought to be terminated with
a note that explains how to pull the VCS audit trail.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>