Changes between Version 7 and Version 8 of BranchingPolicy


Ignore:
Timestamp:
02/10/11 12:05:28 (3 years ago)
Author:
rgrp
Comment:

update for new policy

Legend:

Unmodified
Added
Removed
Modified

  • BranchingPolicy

    v7 v8  
    11= Branching Policy = 
    22 
    3 CKAN is stored in a mercurial repo and we have devised this policy to cope with coding, releasing and maintaining versions of the software. 
     3CKAN is stored in a mercurial repo. This policy covers development and branching policy for this repo. 
    44 
    5 This is based on the [http://www.python.org/dev/peps/pep-0374/#backport 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. 
     5= General: One Branch per Feature and Defect = 
    66 
    7 == Branches == 
     7We will be following the process described in (1) but applied to mercurial. Key aspects: 
    88 
    9 We have a number of maintained branches of the code to reflect their uses: 
     9 1. There will be three 'core' branches: "stable", "metastable" and "default" (in article stable=master and develop=default) 
     10  * stable: stable code 
     11  * metastable: (will soon be deprecated) for code preparing to be stable 
     12  * default: development HEAD 
     13 2. A (named) branch will be created for each feature or defect (bug). Naming convention: 
     14  * defect-{ticket-number}[-optional-name] e.g. defect-902-my-bad-bug 
     15  * feature-{ticket-number}[-optional-name] e.g. feature-903-my-amazing-feature 
     16 3. A (named) branch will be created for each release: release-v{release-number} e.g. release-v1.3 
    1017 
    11 '''default''' branch is for future releases - New features go here. Bug fixes should always go here as well as the other branches. 
     18Feature, bug and release branches may be "closed" once appropriately merged. To summarize the work-flow: 
    1219 
    13 '''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`. 
     20 * No (or almost no) work should be done in default or stable directly. Work in branches. 
     21 * feature branches branch off default and merge back into default 
     22 * defect branches branch off default *or* stable and merge back into respective branches. Fixes on stable get merged to default as appropriate. 
     23  * NB: if a fix needs to go from default to stable (it happens!) then you can use mercurial's transplant (as you obviously must *not* merge from default to stable) 
     24 * release branches branch off metastable (in future off stable) 
    1425 
    15 '''stable''' branch is the latest proper release. It usually lags `metastable`. 
     26More in article (1). 
    1627 
    17 '''ultrastable''' branch is for the most stable code - proper releases, always one behind `stable`. 
     28We also strongly recommend that users push *by default* to their own personal repo rather than the main repo. This allows for code review by another dev before merging into the main repo and should reduce the number of "oops, I've pushed and broken the build" moments. 
    1829 
    19 == Merging between the branches == 
     30== Closing Branches == 
    2031 
    21 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: 
    22  
    23  * 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. 
    24  * 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. 
    25  
    26 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. 
    27  
    28 So the rule is: 
    29  * Releases are merged DOWN the waterfall: `default` -> `metastable` -> `stable` -> `ultrastable` 
    30  * Bug fixes should be merged UP the waterfall: `default` <- `metastable` ( <- `stable` <- `ultrastable` ) 
    31  
    32 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`). 
    33  
    34 (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.) 
    35  
    36 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'. 
     32{{{ 
     33hg up -r {branch-name} 
     34hg ci --close-branch {branch-name} 
     35# may now want to merge to default or you'll be left with a dangling head 
     36hg up -r default 
     37hg merge -r {branch-name} 
     38}}} 
    3739 
    3840== Transplanting changesets == 
    3941 
    40 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. 
    41  
    42 You can either use the mercurial 'transplant' extension or use `hg export` and `hg import`.  
     42When you merge, you can't cherry pick changesets - you have to take all of them up to a certain one. In these cases transplant can be useful to copy a changeset across (though mercurial will not be aware of this copy). 
    4343 
    4444== 'tip' note == 
    4545 
    4646Mercurial 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. 
     47 
     48= Further references = 
     49 
     50 1. http://nvie.com/posts/a-successful-git-branching-model/ 
     51 2. http://forceten.tidalwave.it/development/mercurial-best-practices/ 
     52 3. http://www.rabbitmq.com/mercurial.html#branchperbug 
     53 4. http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/ 
     54 5. Original thread http://lists.okfn.org/pipermail/ckan-dev/2010-November/000034.html 
     55