Branching Model

RADICAL-Pilot (RP) 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. Cannot be merged, they 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.