Re: [Monotone-devel] monotone Hacking

[Zack Weinberg]

On 9/11/07, Richard Levitte <address@hidden> wrote:
> You're talking about two different kinds of documentations.  When I
> update my workspace, or even better, when I'm about to, and I want to
> know what will happen, the most natural is to check out the log.  If
> all the log says is that this and that function was created, this and
> that function was removed, this and that file was renamed to such and
> such, it tells me absolutely NOTHING.

I'm not disagreeing with having "why" in the commit messages, but I
want to put in a good word for including the verbose GNU-style "what"
messages as well.  When you're doing archaeology on a code base, it's
really really helpful if the commit logs specifically name every file
and function that the programmer *intended* to modify with that
commit.  It lets you grep for all changes that touched a particular
thing (file, function, whatever), and it can identify accidental
changes (if the diff says something was modified, but the log doesn't
mention it).

Also, I find writing the detailed logs to be a useful pre-commit
mental exercise.  I never do them while coding; I always do them by
reading back over the current workspace diff just before committing.
I've caught lots of errors, accidental failures to remove debugging
printfs, etc. this way.

zw