Use cases of Mercurial

[Eric Wing]

> Use Case for a DVCS : "What people are
> doing with DVCS that they couldn't do with a centralized repositories".

I think this falls under 'what I couldn't do before without DVCS'
(though maybe I'm not being creative enough…but maybe that's the real
point).

I recently co-authored a book, "Beginning iPhone Games Development".
http://playcontrol.net/iphonegamebook

I co-developed a fairly lengthy code example for the book. The example
was an Asteroids clone game in which one of my co-authors developed to
teach OpenGL in the preceding chapters. I extended his example and
added OpenAL sound effects, 3D audio, background music, and speech
over the course of 3 more chapters.

By the end, there were 17 different way point projects in my chapters
which are given to the readers of the book in the source code
download. Each project way point builds on the previous, with a few
exceptions. There were a few branches/dead-end points where I add a
feature, and then go back and pretend we didn't do that. (I show
multiple, alternative ways of implementing background music using
other APIs on iPhone OS in addition to just OpenAL.)


So obviously, with 17 different way points, if I made a change that
would need to be propagated to subsequent way points, manually doing
this would be very painful and error prone. DVCS removed a lot of the
error risk, though I admit the process was still tedious. Changes
included everything from simple bug fixes, to new features, to total
refactoring of code.

My co-author didn't use Mercurial for his stuff, so I just received a
zip drop which I then created a new Mercurial repository as my origin
point. When he made changes throughout the course of writing, I simply
overwrote the source files in my repo with the new source drop and
then let Mercurial see everything as a new change which I would then
commit.


I also wrote the last two chapters out of order. I wrote the
background music and speech stuff first, and then came back to 3D
audio. So this added more non-linearity to how I did all the changes.
Ultimately, at the end, I just needed to pull the 3D audio changes
into my music and speech branches. All standard operating procedure
with DVCS. (FYI, the 3D audio chapter had 7 projects, and the
streaming chapter had 5.)

I'm not even sure how I would approach this with non-DVCS. I'm glad I
don't have to think about it.


Some other tidbits:
- For this entire process, the only trick was I had to remember that
merges always flowed in one general direction. I screwed up once near
the very beginning and pushed/committed in the wrong direction. Not
being a hard core guru, I didn't know how to erase all those
transactions, so I just started over.

- I used the subrepos extension. This was my third forte into subrepos
with Mercurial. I documented my second and first on my blog awhile
back here:
http://playcontrol.net/ewing/jibberjabber/mercurial_subrepos_a_past_e.html

I actually created two layers of subrepos. One layer of repos to cover
all the projects in a chapter, and a second layer that covered all the
chapters. This would allow me to grab per chapter or fetch the whole
thing. Unfortunately, my repo was password protected so it was a pain
to fetch/push because I kept getting prompted for my password for
every single repo. I used the hgkeychain extension early on, but it
broke on one of the Mercurial updates during the course of my writing
and I never got it fixed.

- Another minor "problem" with the sub-repos is the Mercurial status
webpage. Normally there is an option to download zip/tar files of the
repo. The problem is that I expect to get all the projects that the
subrepos encompass, but you don't actually get that with a subrepo. (I
had volunteers reading my material for feedback and wanted to give
them easy access to my source code.)


- As for Git vs Mercurial, I don't have much to say on this one. In
most cases, I consider the choice somewhat arbitrary. Cross-platform
(particularly Windows), I give Mercurial a slight edge, but for an
iPhone project, that wasn't a concern. However, in this case, my main
external server was on shared hosting and I don't think I'm allowed to
do anything besides http on standard ports. Last I checked (it's been
awhile) Mercurial favored http while Git favored its own custom
protocol. I know Git has http support, but it doesn't seem favored and
I don't like setting any of these things up so Mercurial seemed like
the path of least resistance for this.

- Finally, I don't mention Mercurial explicitly in the book (might
have to write something on my book's webpage about it someday), but
the Mercurial data was not stripped with our source code download, so
an industrious reader would be able to see the revision history.

-Eric