Branching Model

RADICAL-Pilot uses git-flow as branching model (see [1]), with some simplifications. We follow http://semver.org/ for version numbering.

• release candidates and releases are tagged in the master branch (we do not use dedicated release branches at this point).
• a release is prepared by
  • tagging a release candidate on devel (e.g. v1.23RC4)
  • testing that RC
  • problems are fixed in devel, toward a new release candidate
  • once the RC is found stable, devel is merged to master, the release is tagged on master (e.g. v1.23) and shipped to pypi.
• if a hotfix release is required:
  • branch to hotfix/problem_name
  • fix the problem in that branch
  • test that branch
  • merge back to master and prepare release candidate for hotfix release
• devel serves as default branch for development and bug fixes between releases.
  • all activities which require just one (or very few) commits can be committed directly to devel
  • larger activities go into feature branches
    • branch devel into feature/feature_name
    • work on that feature branch
    • on completion, merge devel into the feature branch (that should be done frequently if possible, to avoid large deviation (==pain) of the branches)
    • test the feature branch
    • create a pull request for merging the feature branch into devel (that should be a fast-forward now)
    • merging of feature branches into devel should be discussed with the group before they are performed, and only after code review
  • documentation changes are handled like hotfix or feature branches, depending on size and impact, similar to code changes

Branch Naming

• devel, master: never commit directly to those
• feature/abc: development of new features
• fix/abc_123: referring to ticket 123
• hotfix/abc_123: referring to ticket 123
• experiments/sc16: experiments toward a specific publication etc.
• tmp/abc: temporary branch, will be deleted soon
• test/abc: test some integration, like a merge of two feature branches

For the latter: assume you want to test how feature/a works in combination with feature/b, then:

• git checkout feature/a
• git checkout -b test/a_b
• git merge feature/b
• do tests

Some additional rules:

• commits, in particular for bug fixes, should be self contained so make it easy to use git cherry-pick, so that bug fixes can quickly be transferred to other branches (such as hotfixes).
• do not use git rebase, unless you really know what you are doing.
• you may not want to use the tools available for git-flow -- those have given us inconsistent results in the past, partially because they used rebase...