Re: [Monotone-devel] monotone Hacking

[Richard Levitte]

In message <address@hidden> on Tue, 11 Sep 2007 07:12:54 -0400, Stephen Leake 
<address@hidden> said:

stephen_leake> On the other hand, that is the way we typically work. I
stephen_leake> often notice "little things" while I'm working on one
stephen_leake> "big thing". Would it be better to _not_ fix them? Or
stephen_leake> do one commit for each little thing?
stephen_leake> 
stephen_leake> Documentation belongs in .texi files, not in commit
stephen_leake> messages. Commit messages should help you find when a
stephen_leake> change occured, and give pointers/hints about why, but
stephen_leake> the real reasons should be in more stable form.
stephen_leake> 
stephen_leake> Otherwise, you can get oscillations; "changed to a
stephen_leake> linked list because it's faster on Windows", "changed
stephen_leake> to a red-black tree because it's faster on Gentoo"
stephen_leake> etc. If those comments were in a design file, it would
stephen_leake> be obvious what's happening. If they are just in the
stephen_leake> commit messages, it's much harder to notice.

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 tend to follow pretty carefully what happens (well, apparently not
entirely well, considering I missed the changed of semantics for the
approve command), among others because I've a background as peer
reviewer within programming groups and habits die hard, and for quite
a lot of the log messages, my usual reaction is something along the
lines of "oh, ok, they fiddled with this, that and that, but what the
f*ck does it do??????", and it's quite possible that these are
internal changes that have zero impact on monotone.texi, and the NEWS
file has the unfortunate tendency not to be updated before the next
release (with a few notable exceptions).  And at release time, when
I've tried to figure out what changes have actually happened and what
they mean so I can update NEWS at least a little bit, I've often found
myself saying a series of "what the f*ck"'s (se the quote a few lines
up) and scratching my head.

Documentation in .texi files are fine for user documentation, overall
architecture, roadmaps, that kind of thing, but to understand what
individual changes actually do, it suck 747s through a needles head.
It's simply about traceability.

As for small changes, I see no problem with them getting in as part of
something bigger, and being CLEARLY marked as such.  Some might say
that it's better to try to make them into separate commits, but I
personally wouldn't care.  If you CAN make them into separate commits,
then do.

Cheers,
Richard

-----
Please consider sponsoring my work on free software.
See http://www.free.lp.se/sponsoring.html for details.

-- 
Richard Levitte                         address@hidden
                                        http://richard.levitte.org/

"When I became a man I put away childish things, including
 the fear of childishness and the desire to be very grown up."
                                                -- C.S. Lewis