Mercurial Branching

[A. S. Budden]

Dear all,

As you may have gathered from my email earlier in the week, we have
decided to move from Bazaar to Mercurial.  I'm in the process of trying
to work out how we're going to use Mercurial in a way that is most
suited to our environment and was hoping I could seek some
opinions/advice on this.  There may be more of these emails to follow,
so I beg your patience and I hope it's okay to refer back to the 'some
background' section in any later emails!

----------------------------------------------------------------------

Some background:

As a general rule, most of our projects have a small number of
developers (typically between one and three).  Very occasionally there
are more developers involved, but the entire department is only 12
people, so we never really get into large numbers of developers on one
project.  A single developer will often be working on multiple projects,
although that probably doesn't make any difference to this discussion
except to say that anything that has to be remembered regarding what's
happening on a project will probably be forgotten as soon as the
developer gets 'redirected' onto another project for a week or so.

Projects are mostly (deeply) embedded C source, mostly built with Keil
uVision or Freescale Codewarrior (which both have essentially
un-mergeable project files), with a few (mainly python+Qt) PC
applications used for development testing.  We make fairly heavy use of
'library modules' (sub repositories) such as a communications stack,
which are currently all in the 'LibraryModules' folder of the projects
that use them: these library modules are probably the ones that have the
most developers involved.

All projects are stored in a Category/Project hierarchy on our 'F:'
network drive, which is backed-up very regularly.  Some users work on
their 'home' network drive, but most are migrating over to working on C:
(for compilation speed) and using 'SyncToy' to ensure their work is
backed-up to the home drive.  All users use Windows and pretty much
everyone (except me) strongly likes using GUIs so will be using
TortoiseHG pretty much exclusively.

At the moment, we have a central Bazaar repository on the 'F:' drive
with a number of branches stored within.  We currently use a branch
called 'development' for active development, one called 'code_review'
for code from the development branch waiting to be merged to trunk and
then the trunk for reviewed code ready to be released (releases are
tagged and sometimes a branch is created for good measure).  I expect to
translate this fairly directly over to Mercurial using named branches
(development becomes default, trunk becomes release and code_review
keeps the same name).

>From the 'development' branch, there are often 'feature' branches that
are created.  These are typically short-lived (create a branch, do a few
commits of code, then merge back into development).  As we're using
Bazaar's heavyweight checkout model, all of these branches go into the
F: drive repository.  Because we use the centralised model at present,
where there are multiple developers, we'll often have 'user' branches as
well, so you get:

    trunk - development - user-abc - feature-xyz

rather than:

	trunk - development - feature-xyz

When using feature branches, we generally encourage regular commits,
regardless of whether the code compiles/lints/tests cleanly - this makes
it nice and easy to try different approaches whilst still being able to
go back to earlier versions.  Anything that goes into development (and
even more so, trunk) should compile/lint/test cleanly (although I'm not
convinced that this rule is enforced at the moment: a build server is in
the budget for this year!).  So in Bazaar looking at the development
branch, we can be fairly sure that revisions 515, 516 and 517 are
'good', but 515.1, 515.2, 515.2.1 etc may well be 'bad'.

----------------------------------------------------------------------

Moving to Mercurial and a properly distributed way of working, I expect
that we won't bother with the user branches (as each will effectively be
working on a separate branch by having a local clone on their hard
disk). (Comments?)

I had been thinking that we'd probably use 'bookmarks' for feature
branches as they are relatively short-lived.  Do you think this is a
good idea?  There's a risk that (if commit messages are poor) the
feature branches may get lost in the 'noise' of the history.  Also they
are private to developers so if two developers ever work together on a
feature, they have to bookmark it independently.  I know Mercurial allows
bookmark pushing, but (a) it's not automatic, so most people probably
won't do it and (b) I can't see how to do it in TortoiseHG, so most
people in my GUI-obsessed department can't do it.

I've also been reading Greg Ward's recent emails on the mailing list and
they've scared me somewhat with regards to bookmarks.

Using named branches instead of bookmarks might therefore be better.  I
guess we can 'suggest' a naming convention (e.g. feature-* user-* etc)
for 'temporary' branches, but they will probably stay in the history
forever.  I doubt they'll ever be deleted as it looks a bit convoluted
to do so (am I right about this?):

    1. Finish working on the feature branch
    2. Update to 'default' (or whatever the upstream branch is)
    3. Merge the feature branch
    4. Update to the feature branch
    5. Close the feature branch
    6. Update to 'default' again

I doubt anyone will do steps 4-6 as all they do is shorten the list of
branches.  Perhaps they would if there were a simple way to do all three
steps in one (GUI) go (i.e. close a branch other than the one that
you're currently 'on' or, even better, a combined 'merge-and-close').

----------------------------------------------------------------------

Does anyone have any experience of working in a similar kind of
commercial environment with Mercurial?  Can anyone offer any good
suggestions as to how we might approach this?  Since we're just starting
off with Mercurial, we can probably make relatively significant changes
to the way we do things as long as there's an obvious benefit.

Apologies for the long email and thanks in advance for your suggestions.

Regards,

Al