[cairo] Let's avoid uninteresting merges please

[Carl Worth]

As we work with git and simultaneously make separate commits, we often
have to merge them. Sometimes, this is an "interesting" merge such as
pulling in an entire branch of potentially many commits. In such a
case, the merge message names the branch of interest. For example:

	Merge branch 'analysis-surface' into cairo
	4fd30e6f402ae031c2084c20f136b84307a128cc

But at other times, the merge is really boring---it might be the merge
of two patches that touch disjoint sets of files. For example, the
most recent boring merge commit in cairo is:

	Merge with git+ssh://git.cairographics.org/git/cairo 
	807f64d57c616e2ce8a61202cd9b59ac7a6a26cb

Here, we have an auto-generated commit message that really doesn't
have any useful information in it. Worse, the URL here changes from
one boring commit to the next, while some also mention 'master',
'origin', 'cairo', or 'cairo-origin'. So when browsing through the
history it sometimes takes a few moments of study to realize that this
commit object is totally boring and should be ignored.

I think these boring commits only add clutter to our history, and I
think it would be worth our putting in a little extra effort to avoid
making them.

I mean no offense to Anders in pointing at the above commit. The
git-pull command makes it really easy to make these ugly things.  It
would be even better if git's commands for following upstream would
automatically avoid these, but in the meantime, here's a recipe to
follow.

First, here's how a boring merge commit results---then the recipe
follows below that.

What leads to a boring merge commit
-----------------------------------
I'm going to sit down and do some hacking. I fetch/pull the latest
upstream code, but while I'm working someone else pushes before I get
done:

	git pull origin		# get latest changes
	hack, hack, hack	# meanwhile, someone else is hacking
	git commit		# ... and they are committing
	git push		# ... and they pushed first

In this case, the git-push will fail with a message along the lines
of:

	error: remote 'refs/heads/master' is not a strict subset of
	local ref 'refs/heads/master'. maybe you are not up-to-date
	and need to pull first?

So, being obedient, I execute the following:

	git pull origin		# merge with upstream

And if all goes well this results in a "really trivial in-index
merge... Wonderful" message and it also makes the boring commit
object. If I push at this point, we'll have that boring commit forever
in cairo's history. So let's not push just yet.

Note: If the really trivial merge fails, then git leaves me with a
conflict to resolve. After resolving this conflict I think it does
make sense to go ahead and commit a new merge commit object. Then it's
not so boring as the merge is associated with real, manual merge work
I did, (and my commit message should reflect that).

How to use git-rebase to avoid pushing a boring merge commit
------------------------------------------------------------
Picking up on the command sequence above, we just did a git-pull that
merged in upstream changes and made a new, boring merge commit object,
that we don't want to push.

1. Throw away the boring commit

	git reset --hard HEAD^

2. Rebase my local changes onto the tip of the tree:

	git rebase origin

That's it. Now things are ready to be pushed out with "git push
 origin".

I don't think this is too much work. Though I will admit that any
recipe that has "git reset --hard" in it is a bit scary. If someone
wants to submit a patch upstream to git for rebasing-pulls that might
be interesting.

And the rebase here should be pretty much guaranteed to work since I'm
only suggesting we do this after a really trivial merge has already
been demonstrated to be successful.

Thanks for your attention, and thanks for your efforts to keep cairo's
code (and history) as clean as possible.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060410/97acb9c4/attachment.pgp