Subject: Re: Please stop change logs in CVS commit messages
To: Todd Vierling <firstname.lastname@example.org>
From: David Burgess <email@example.com>
Date: 07/10/2001 16:52:12
Todd Vierling wrote:
> On Tue, 10 Jul 2001, David Burgess wrote:
> : A CVS update like "Fixed a bunch of broken stuff" is insufficient.
> : A rambling, chatty-cathy description of every line of changed code is
> : too much. There has got to be a happy summary limit in there someplace.
> Which would be fine, provided we define a proper commit log format. But a
> lot of commits have been just of raw ChangeLogs or READMEs, not necessarily
> as long as the example I provided, but just as annoyingly useless.
> "A summary of the changes" (not specifically defined) isn't really useful as
> a requirement for the pkgsrc commits.
The part of the message you didn't quote basically agrees with you.
There *MUST* be a reason for making the change. If it wasn't done in
response to a PR, then what was the impetus. A ChangeLog is
insufficient, not because it's too much or too little, but because
it (in and of itself) wouldn't explain WHY the change was made.
A summary of changes *with an explanation of why the change was made*
would, on the other hand, be sufficient. As a CM guy, my concern is
that we are making headway on reducing the number of open PRs we have
(which the current system seems to address nicely) and that the changes
to the system are not capricious.
IFF a change is capricious, then the commit message should say so.
Same with style changes, The One True Brace Style (TOTBS) changes, and
a lot of other reasons. The thing that worries me on commit lines is
"Fixed a bunch of stuff" or "New code works better".
Now, I'm not advocating that we included "War and Peace" for every
change, especially since our database of PRs can easily be used to
identify the changes that were made. Commit messages like 'Closed
PR 3487, 3488, and 2000030 by changing the spelling of "whale" to
"while"' provide the impetus for the change as well as a summary of
the change. Even "Fixed PR 3487 ..." without the fix is OK, but at
least we have some way to trace back the why and a reasonable what.
Now that I've started work on my Doctorate, this kind of thing is going
to get more and more important to me. NetBSD is going to figure
prominently in my Thesis - I just don't know how yet. As such, I'm
going to have to keep close track of not just my changes, but y'alls
as well. My Thesis committee has already made it clear that whatever
I end up doing is going to have to be my work, so I'm going to have to
give credit as well as showing what I did. I doubt they'd look
on really terse or really long CVS commits.
So, if only to help me, we need to come to some kind of consensus on
what makes a 'reasonable' CVS commit message.