Branching and Release Strategy

  • Status: accepted

  • Deciders: devs, devops

  • Date: 2020-05-24

Context and Problem Statement

How do we want to organise work in branches and how should changes be released? How should different branches be continuously deployed for QA?

Decision Drivers

  • We need to have confidence in our releases.

  • We want more structured releases while we're still getting our footing in a shared monorepo.

  • We need simplicity and clear takt time so different teams can plan for what is going out the door from them.

  • It should work well with our agile work environment.

Considered Options

Branching strategies:

Release strategies:

Decision Outcome

Chosen option: "OneFlow" because it provides a single eternal branch with well structured releases.

We'll implement OneFlow with these details:

  • Release branches are set up the Monday after each sprint. This is sometimes called release trains, where features line up for different release trains.

  • Release and quality managers from each team are responsible for reviewing and approving releases.

  • Releases apply to all apps in the monorepo.

  • Releases are versioned like this: {cycle}.{sprint}.{hotfix}. So version 3.1.2 is the release after cycle 3, sprint 1 with two hot fixes applied.

  • Feature branches are merged using "Squash and merge", so they can be easily reverted.

  • There are two ways to build larger features.

    • If the feature is isolated and not likely to cause conflicts, they can stay on long-living feature branches until they are ready to be released.

    • If the feature touches many parts of the codebase, it can be useful to merge changes more often but hide the feature in production with feature flags.

  • If a project needs to deploy updates outside of the sprint rhythm, they should use hotfix branches.

Future strategy

With time, we expect to build up better testing capabilities which gives us more confidence in the health of our monorepo. Then we can move quicker, with a simpler GitHub Flow branching strategy and continuous delivery into production.

Hosting environments

We'll set up continuous delivery to different hosting environments:

EnvironmentGit sourceDatabases/servicesFeatures


feature branch












release/hotfix branch




latest release tag



We'll probably start with dev, staging, pre-prod and prod environments, since feature branch deployments are more dynamic and difficult to manage.

Pros and Cons of Branching Options

Git Flow

  • Good, when there needs to be multiple versions in production.

  • Good, because it enforces an easy to comprehend naming convention for branches.

  • Good, because it has good support in popular git tools.

  • Bad, because the git history becomes unreadable.

  • Bad, because the main/develop split is redundant.

GitHub Flow

  • Good, because it fits well with Continuous Delivery and Continuous Integration.

  • Good, a simpler alternative to Git Flow.

  • Good, when we need to maintain a single version in production.

  • Bad, because production code can become unstable most easily.

  • Bad, if we need release plans.

One Flow

  • Good, because it has a clean git history (with squash-and-merge).

  • Good, because it has a structured release process without multiple long running branches.

  • Good, because it has good parts from GitHub Flow (simple history with one branch + feature branches) and Git Flow (releases and hot fixes).

  • Bad, because it makes continuous integration more difficult.

Pros and Cons of Release Options

Continuous Delivery

  • Good, because it is simpler and leaner, allowing changes to be deployed quicker.

  • Bad, because it can easily break something in production if our CI isn't good enough.

Release trains

  • Good, because it has more structured releases, which helps with planning and QA.

  • Good, because it can be synchronised to organisational schedule.

  • Good, because it gives us a process to verify and test each release.

  • Bad, because it is fairly rigid and complicated to implement organisation-wide.

Last updated