[Kde-games-devel] kblocks new version...

[Parker Coates]

On Thu, Jan 21, 2010 at 04:21, Dapeng Zhang wrote:
> Tadeusz Andrzej � wrote:
>> - Avoid huge commits. A series of smaller changes is easier to track for other
>>   people. Work in the open.
>>
> I thought that people will be fed up by small changes...

Quite the opposite. Ideally only one significant change should be made
in each commit. There are plenty of reasons for this.

Let's imagine we just noticed a new bug in KBlocks. We know the bug
hasn't always been there, but it's appeared sometime in the last 6
months. We can now do start trying out commits to try to pinpoint the
commit that added the bug. (Using a tool like big-bisect this is now
pretty easy.) Once we find the commit that introduced the bug, we're
hope it's a nice small commit with a clear commit message. That way
we'll only have to look through a dozen changes or so to find the
breakage. A 600 line commit, however, makes that much more onerous,
because there's more changes to read through and those changes
probably aren't all directly related.

Now let's say, we found the source of the bug, but it wasn't just a
typo or mistake. It turns out the problem was the change in question
wasn't properly thought out and should never have been made in the
first place. If the change was made in its own commit we just need to
revert that commit, which is very easy. If it was made as part of a
mega commit, we have to go through that commit line by line to
determine what we want to keep and what we want to revert.

Never worry about bothering people with your commits. If someone is
actually tracking your commits, then the most likely are interested in
what your doing. And a dozen small commits will always be easier to
read than one large one. Making small, frequent commits allows such
people to see in roughly real time what your doing. This has several
benefits. It allows them to make suggestions when you could actually
make the best use of them. It allows them to point out problems before
too much effort has been wasted.

And finally, small commits tend to be much better documented and are,
in certain senses, self documenting. Each commit will have a minimum
of one line of description, but usually more. If you commit 2 weeks of
work all at once, chances are you won't be as detailed in the single
description. You'll also lose the sequencing of the changes that you
get automatically with a series of smaller commits.

Wow, I just wrote way more than I intended. Please don't take this as
a personal attack, Dapeng. :) I just got carried away.

Parker