Branching Model

RADICAL-Pilot uses git-flow as branching model, with some simplifications. We follow semantic 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.
• urgent hotfix releases:
  • branch from master to hotfix/problem_name
  • fix the problem in that branch
  • test that branch
  • merge back to master and prepare release candidate for hotfix release
• normal bug fixes:
  • branch of devel, naming convention: fix/issue_1234 (reference github issue)
  • fix in that branch, and test
  • create pull request toward devel
  • code review, then merge
• major development 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 fix 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, to be released right after merge to master
• experiment/sc16: experiments toward a specific publication etc - not mergeable, will be converted to tags after experiments conclude
• project/xyz: branch for a dedicated group of people, usually contains unreleased features/fixes, and is not expected to be merged back
• 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

Branching Policies

All branches are ideally short living. To support this, only a limited number of branches should be open at any point in time. Like, only N branches for fixes and M << N branches for features should be open for each developer - other features / issues have to wait.

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...