CKAN is stored in a mercurial repo and we have devised this process to cope with coding, releasing and maintaining versions of the software.

We have three branches of the code to reflect their uses:

default branch is for future releases - New features go here. Bug fixes should always go here as well as the other branches.

metastable branch is for releases deployed to ckan.net and similar servers. These servers get new features first. Sometimes there are issues to be resolved with these new features. It usually lags default.

stable branch is designed for the most stable code. It usually lags metastable.

(From now on) merges must only be done in the DOWN direction (in the direction default->metastable->stable) and only when you release. So you can release default to metastable with a merge, and from metastable to stable, but you mustn't merge metastable to default, for example. And not when you simply fix a bug.

The problem with merging in the other direction is that a bugfix changesets on metastable may well be mixed in with changesets incrementing the minor digit of the version number. The version number on the default branch may already have a higher major version and you don't want to overwrite it with the metastable changeset. When you merge you can't pick and choose changesets - you have all up to a certain one - so you can't merge in this direction.

You might have written a bugfix in default that you want in metastable too, but don't want the rigmorole of releasing at this point. In this case, don't merge - the problem with merging when you're not releasing, is that you may well pull half-finished features from default into branches which need to be more stable.

The solution (instead of 'hg merge') is to 'hg export' particular changesets from one branch and 'hg import' it to another.

Notes

tip is what Mercurial tags the latest commit. So it changes on every commit and might be on any branch. So it's best not to refer to it in documentation, emails or changeset comments.