Skip to content

Branching Model

Jump to bottom
Andre Merzky edited this page Feb 28, 2018 · 11 revisions

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.
  • 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...
Clone this wiki locally