Git branching model

We use a simplified version of the branching model described at http://nvie.com/posts/a-successful-git-branching-model.

• master. stable releases. Each release is tagged. Merges into master only come from devel and hotfix branches.
• devel. unreleased complete and tested features.
• Unless otherwise specified, only Mark Howison can modify and merge into master and devel. There are a couple of exceptions when analysis code is not modified in any way. These include changes to documentation, which can be made directly in devel and, more rarely, in master. New tests should be added in feature branches, and if they all pass initially (i.e., no changes are needed to the base code) the author can merge them directly into devel.
• feature branches. These should be named after the corresponding issue number, eg issue-47. Feature branches always branch from devel and are merged into devel. They can only be merged into devel when the feature is complete and ready for release, the branch has successfully passed the agalma test regression test, the branch has passed all unit tests with python setup.py test, and the code has been reviewed. The typical workflow is that once the tests are passing, the author of the feature branch notifies Mark Howison that it is ready for code review and merging. They should be merged into devel with --squash, eg git merge --squash issue-58, so that a single, new commit object is always created. Do not delete the feature branch, and be sure to push it to the bitbucket repository, since that will retain all the individual commits from the feature's development.
• hotfix. Hot fixes can be applied to master in limited circumstances. If these fixes are on code rather than documentation, they should be made on the hotfix branch and tested with agalma test and unit tests with python setup.py test prior to being merged into master. After the hot fix has been applied to master, master should be merged into devel so that the changes are applied to the development branch as well.
• release branches. These should be named after the release number, eg release-0.5.0 and are branched from devel once all feature branches going into the release are finished and merged into devel. The release branch is a place to commit all the small edits that happen while testing and preparing the release (eg bumping the version, testing out pip install, updating the install instructions and README, etc.). One the release is fully tested, the release branch is squash merged into devel with a message like "finished testing release 0.5.0", and then devel is squash merged into master with the release number as the message, eg "0.5.0".

Pull requests must pass agalma test prior to being pulled. Pull requests should be applied to their own branches that are branched off devel. The regression test should then be reapplied, and if it passes then the branch is merged back into devel with --squash (as for feature branches).

Commit messages should include references to issues so that it is clear which issues have been addressed or are in the process of being addressed. More on Issue Services at https://confluence.atlassian.com/display/BITBUCKET/Setting+Up+the+Issues+Service.

Typical use case

The following is a typical use case for a new branch:

git clone https://caseywdunn@bitbucket.org/caseywdunn/agalma.git
cd agalma
git checkout devel
git pull
git checkout -b issue-49
# Make some edits
git commit -am "added argument re #49"
# Push the issue branch
git push -u origin issue-49
python setup.py test # Only proceed with the next steps if the test passes
agalma test # Only proceed with the next steps if the test passes
git checkout devel
git merge --squash issue-49
# The squash leaves the modified files in the working copy, and they need to be committed
git commit -am "Fixes #N: description..."
# Push the merged devel branch
git push origin devel

The following is a typical use case for a new release:

git checkout devel
git merge master # fix any conflicts
git checkout -b release-0.5.0
# make all commits resulting from testing the release
git checkout devel
git merge --squash release-0.5.0
git commit -am "finished testing release 0.5.0"
git checkout master
git merge --squash devel
git commit -am "0.5.0"
# sync up all the branches with the new master commit
git checkout hotfix
git merge master
git checkout devel
git merge master

BioLite branching model

BioLite uses the same branching model as agalma. If a change to BioLite corresponds to modifications of agalma, the BioLite feature branch should be named accordingly, eg agalma-issue-N