Obsolete - Feature Branching with Bookmarks

Background

Feature Branches

Feature branches are used to allow long-running dev tasks to be committed (and hence integrated and tested) while keeping `default` in a working state. We've used them extensively since moving to Mercurial.

Named Branches

To date we've used Mercurial's named branches for feature branches. Named branches cannot be renamed or deleted, which leads to a few of issues

• poorly named branches
• a long list of branches in TeamCity, Tortoise and hg
• most dangerously, branches that have ended up in a broken/unusable state

Bookmarks

For named branches, the name of the branch is set on every commit to the branch - this is why you cannot modify them. Bookmarks are a light-weight alternative: they are essentially a pointer to a commit, that moves along. They work similarly to branches in git. Because they are just a pointer, they can be renamed, deleted or moved to point at a different commit quite easily. Bookmarks don't come without issues though:

• You need to explicitly push a bookmark the first time you want to share it, with: 

         hg push -B <bookmark> 

• having multiple bookmarks on a branch means that you will end up with multiple heads on that branch (one for each bookmark). This isn't an issue as such, but it does mean that you can no longer meaningfully use that branch (because when you update to it, you have no way of knowing which head you'll get). In practice this means that you need a 'base' bookmark that is a clean place to branch from.

Here's a picture

On the left is a standard named branch structure; on the right a bookmarked structure. As you can see, with bookmarks 'default' has two heads (changesets 3 and 4). When you're at the bookmark f-blah and commit, the bookmark moves to that new changeset (changeset 5).

Branch setup

We have a branch called 'features' that all feature bookmarks should come off. This is the only branch that should have multiple heads. We have a bookmark called 'f-head' that tracks the clean state of 'features'. 'f-head' is where you start your feature branch from.

TeamCity treats bookmarks just like branches, so nothing changes there.

Process

Update Mercurial

Bookmark support has improved a lot in the last couple of hg releases, so make sure you're using the latest version (>2.8.1).

Create a new feature bookmark

• Make sure f-head is up to date:

  hg pull
  hg update f-head
  hg merge default
  hg commit -m "default -> f-head"

• Create your new bookmark from f-head:

  hg bookmark f-blah

• Do some work

• Commit and share your bookmark. NB, you may need to --force the push because you may be creating a new head:

  hg commit -m "Intial commit for f-blah"
  hg push -B f-blah [--force]

• Periodically merge default as usual:

  hg merge default
  hg commit -m "default -> f-blah" 

Get your changes to default

• Merge to default as you usually would (make the commit message descriptive as it's encapsulating all the work on your branch):

  hg merge default
  hg commit -m "default -> f-blah"
  hg update default
  hg merge f-blah
  hg commit -m "f-blah -> default for RM-XXXX: make blah work"

• Delete your bookmark if the feature is done (nb, you need to push with -B):

  hg bookmark -d f-blah
  hg push -B f-blah

• Push your changes to default:

  hg push

Update to someone else's bookmark

• Just like with a branch:

  hg pull
  hg update f-blah

Misc bookmark actions

• List bookmarks: hg bookmarks
• Rename a bookmark: hg bookmark -m f-blah f-newblah
• Move (or create) a bookmark to a given revision: hg bookmark -r 123 f-blah