Branching Policy

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

This is based on the ​system used to develop Python, but instead of naming branches after their version numbers, they are named after the maturity of the release, which suits our more frequent releases. This allows metastable to always to be a beta, stable to be the latest solid release and ultrastable to be the previous-but-one release.

Branches

We have a number of maintained 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 beta releases and proper 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 the latest proper release. It usually lags metastable.

ultrastable branch is for the most stable code - proper releases, always one behind stable.

Merging between the branches

This arrangement can be seen to be like a waterfall of changesets. default has the most, metastable is a subset of default, stable a subset of metastable etc. As the releases go down the waterfall, the bug-fixes go in the opposite direction:

• A branch may need a bug-fix, and this would need to be merged to all branches UP the waterfall. Even if the bug-fix no longer applies on default (because say the file in question has been completely refactored in the meantime), this isn't a bad thing, since you'll be alerted when you get a conflict during the merge.
• Along with the bug-fix it may be worth adding a version change (e.g. 1.2 to 1.2.1). This would also be usefully merged with the bug-fix up the waterfall, indicating the bug is fixed in these places too.

Unless there is a big need for a bug fixes on the more stable branches, bug fixes are best done on metastable (and then merged just to default). This saves the more stable branches from the risk of bug fixes causing other bad effects.

So the rule is:

• Releases are merged DOWN the waterfall: default -> metastable -> stable -> ultrastable
• Bug fixes should be merged UP the waterfall: default <- metastable ( <- stable <- ultrastable )

It is good to merge all branch changes up the waterfall to the top, so that you don't forget to apply a bugfix to a higher branch. In the process of doing this, you close the branch heads on the way. So when you push new changesets onto a branch (aside from default), you should expect to be reminded to create a new head (hg push -f).

(We've not thought of a use case that needs this, but there is a possibility that you want to make a change to a branch, which you don't want merged up the waterfall and wouldn't cause a conflict. If this should arise you can still merge upwards, but manually revert the change before committing it. But this would be against the grain of this waterfall model and if this becomes frequent, this policy should be reconsidered.)

If you merge bug fixes the wrong way (i.e. down the waterfall), you may well end up with unstable changesets merged as well as the bugfix! If you find you have fixed a bug on a higher branch than necessary and want to have the bugfix on a lower branch, then you need to 'transplant' the changeset, rather than 'merge'.

Transplanting changesets

When you merge, you can't cherry pick changesets - you have to take all of them up to a certain one. So you have to be slightly more cunning to 'transplant' a bugfix changeset down the waterfall.

You can either use the mercurial 'transplant' extension or use hg export and hg import.

'tip' note

Mercurial tags the latest commit with the tag tip. This means 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.