Changes between Version 2 and Version 3 of BranchingPolicy

Timestamp:

08/26/10 14:21:02 (4 years ago)

Author:

dread

Comment:

Clearer. Info on transplant.

BranchingPolicy

@@ +1 @@
+= 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.
 
@@ -5 +7 @@
 '''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`.
+'''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 for very stable code - major releases. It usually lags `metastable`.
+'''stable''' branch is the latest proper release. It usually lags `metastable`.
 
-'''ultrastable''' branch is for the most stable code - major releases, one behind `stable`.
+'''ultrastable''' branch is for the most stable code - proper releases, always one behind `stable`.
 
-(From now on) merges must only be done in the DOWN direction (in the direction `default`->`metastable`->`stable`->`ultrastable`) and only when you release. This means that you would release `default` to `metastable` with a merge, and from `metastable` to `stable`, but you must not merge `metastable` to `default`, for example. And not when you simply fix a bug.
+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. This is a reasonably accurate view, even working with these edge cases:
 
-The problem with merging in the other direction is that 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.
+ * 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.
 
-You might have written a bugfix in `default` that you want in `metastable` too, but don't want the rigmorole of releasing all the code in `default` at this point. In this case, don't merge - the problem with merging, is that you may well pull half-finished features from `default`.
+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` 
 
-The solution (instead of `hg merge`) is to `hg transplant` (or `hg export` + `hg import`) particular changesets from one branch to another.
+(One future problem with this system might arises when you want a change on a branch which you don't want merged up the waterfall and wouldn't cause a conflict. We've not thought of a use case like this, so we will deal with not being able to merge upwards, it if it arises.)
+
+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`).
+
+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 ==