What is Mercurial?

Mercurial is a fast, lightweight Source Control Management system designed for efficient handling of very large distributed projects.

We use Mercurial on the RabbitMQ project to manage almost all our source-code.

• Mercurial has numerous tutorials.
• RabbitMQ's Mercurial repositories are listed here. Individual project pages on this website will generally point you in the direction of the specific combinations of modules you'll need to check out.

Branching policy: Branch per bug

We use the technique of branch per bug when developing RabbitMQ code, where each feature or bug fix is developed on a branch of its own (using hg branch) and merged into the default (trunk) branch only when the hurdle of QA is passed. We use our Bugzilla instance to track each work item, so branches follow the pattern bugNNNNN.

More information on this style of development can be found in the following links:

• Mercurial Merge Technique on the LShift blog.
• Dealing with multiple named branches in a repository from the Mercurial book.

One consequence of this technique is that it is vital that you do not use the 'tip' of repository as the basis for any work. The 'tip' points to the last commit, which could have happend on any, possibly highly experimental, branch. Instead all development work must be based on (the tips of) named branches, or tagged revisions.

The default branch

The default branch contains all the work that has been QA'd so far that is scheduled to appear in the next release. The default branch of each RabbitMQ repository is usually roughly in sync with the default branches of the others. Generally, you can track QA'd development work by tracking the default branches of the RabbitMQ repositories of interest.

Maintenance branches

Sometimes we create branches for maintenance work, which are used for bug-fixes for a particular release. An example of this is the v1_5 branch which appears in a number of RabbitMQ repositories. Such branches play the same role as the default branch except that they carry merged, QA'd code intended for the next bug-fix release rather than the next general release.

Tags

We also use tags to give names to snapshots of the state of the code. Generally, both the core repositories and the repositories of plugins intended to work with the named snapshot are tagged.

For example, if you are using RabbitMQ server version 1.5.3, then examining the output of hg tags in a copy of rabbitmq-stomp gives:

$ hg tags
tip                               93:9cd7eba4269c
rabbitmq_v1_5_3                   91:5ee5e2c0b64a
rabbitmq_v1_5_1                   65:2eba20816126
rabbitmq_v1_5_0                   60:1a1ff5067bb6
rabbitmq_v1_4_0                   49:71b922193057
Migrated to mercurial             11:a28eea2c2a2b

It's important to make sure that all the repositories you are using are on the same tag as each other. Continuing with our example of server version 1.5.3, you could make sure your checkout of rabbitmq-stomp was at the rabbitmq_v1_5_3 tag by using hg update:

hg update rabbitmq_v1_5_3

At this point, you could proceed with compiling the plugin as explained in the plugin's documentation.

If there is no specific tag for a repository for the version of the server you are using, try using the newest tag that has the same major and minor version number. For instance, if you were running RabbitMQ server version 1.5.4, but no corresponding tag on rabbitmq-stomp was available, you should try using tag rabbitmq_v1_5_3. Another alternative for this hypothetical situation would be to use the tip of the 1.5.x branch:

$ hg branches
default                        93:9cd7eba4269c
rabbitmq_v1_3_0_branch         45:90dd1726fe0b
v1_5                           92:0ba97fbaea1f (inactive)
$ hg update v1_5
4 files updated, 0 files merged, 5 files removed, 0 files unresolved
$