Mercurial Workflow: Feature seperation via named branches

Also published on Mercurials Workflows wikipage. Originally written for PyHurd: Python bindings for the GNU Hurd.

For Whom?

If you

1. want to develop features collaboratively and you want to be able to see later for which feature a given change was added or
2. want to do changes concurrently which would likely affect each other negatively while they are not finished, but which need to be developed in a group with minimal overhead,

then this workflow might be right for you.

Note: If you have a huge number of small features (2000 and upwards), the number of persistent named branches can create some performance problems for listing the branches (only for the listing!) (as different example, pushing is unaffected: Linear history is just as fast as 2000 branches). For features which need no collaboration or need only a few commits, this workflow also has much unnecessary overhead. It is best used for features which will be developed side by side with default for some time (and many commits), so tracking the default branch against the feature is relevant. To mark single-commit features as belonging to a feature, just use the commit message.

Note: The difference between Mercurial named branches and git branches is that git branches don’t stay in history. They don’t allow you to find out later in which branch a certain commit was added. If you want git-style branching, just use bookmarks.

Note: If you avoid using stable as branch name, you can always upgrade this workflow to the complete branching model later on.

What you need

Just vanilla Mercurial.

Workflow

The workflow is 6-stepped:

1. create the new feature,
2. Implement and share,
3. merge other changes into it,
4. merge stable features,
5. close finished features and
6. reopen features.

Let’s see the steps in detail.

1. New feature

First start a new branch with the name of the feature (starting from default).

hg branch feature-x
\# do some changes
hg commit -m "Started implemented feature-x"

2. Implement and share

Then commit away and push whenever you finish something which might be of interest to others, regardless how marginal.

You can push to a shared repository, or to your own clone or even send the changes via email to other contributors (for example via the mailbomb extension).

3. Merge in default

Merge changes in the default branch into your feature as often as possible to reduce the work necessary when you want to merge the feature later on.

hg update feature-x
hg merge default
hg commit -m "merged default into feature-x"

4. Merge stable features

When your feature is stable, merge it into default.

hg update default
hg merge feature-x
hg commit -m "merged feature-x"

5. Close the branch when it’s done

And when the feature needs no more work, close the branch.

\# start from default, automatic when using a fresh clone
hg update default
hg branch feature-x
\# do some changes
hg commit -m "started feature X" 
hg push 

\# commit and push as you like

hg update default
hg merge feature-x
hg ci -m "merged feature X into default"
hg commit --close-branch -m "finished feature X"

This hides the branch from the output of hg branches, so you don’t clutter your history.

6. Reopen the feature

To improve a feature after it was officially closed, first merge default into the feature branch (to get it up to date), then work just as if you had started it.

hg up feature-x
hg merge default
hg ci -m "merged default into feature X"
\# commit, push, repeat, finish

Generally merge default into your feature as often as possible.

Epilog

If this workflow helps you, I’d be glad to hear from you!

For a more extensive project-workflow, have a look at the Complete Mercurial Branching Strategy. It extends the feature branches workflow to account for release cycles.