In message <[EMAIL PROTECTED]> on Tue, 11 Sep 2007 07:12:54 -0400, Stephen Leake <[EMAIL PROTECTED]> 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 [EMAIL PROTECTED] 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 _______________________________________________ Monotone-devel mailing list Monotone-devel@nongnu.org http://lists.nongnu.org/mailman/listinfo/monotone-devel