ADR-0030 Use GitLab Flow

Date2021-11-30
StatusAccepted

Context

A number of different branching strategies are available for git projects. For a while, Git Flow was popular, but it has fallen out of favour because of the complexity of maintaining many active branches. At the other end of the spectrum is Trunk-based development where almost everything happens on one branch (the trunk), and in between we have GitHub Flow and GitLab Flow.

There is not a great deal of difference between GitHub Flow and GitLab Flow, but the latter is more integrated with the GitLab platform (issues and merge requests) and comes with a GitLab Flow Best Practices guide.

Decision

We will use GitLab Flow for eTryOn software projects and do our best to adhere to the GitLab Flow Best Practices guidance.

Consequences

What this means in practice is:

  • We will create feature branches for new features and bug fixes. These will be created from the main branch and will generally be small and short-lived.
  • We will create merge requests to merge a feature branch to the main branch.
  • All tests must pass on the feature branch before it is merged to the main branch.
  • Code review must pass on the feature branch before it is merged to the main branch.
  • We will use semantic versioning for releases.
  • We will create a release branch, release-X.Y, from the main branch.
  • We will create a tag from the release branch, vX.Y.Z. Creation of the tag will trigger CI/CD to build artifacts for release.
  • If we need to fix a bug in a released version of the software, we will:
    • Create a feature branch from the main branch
    • Fix the bug in the feature branch
    • Test, review, and merge the bugfix to the main branch
    • Cherry-pick the bugfix commit to the release branch
    • Increment the patch version and create a new version tag

Some projects (e.g. techdocs, proofs of concept) do not have versioned releases, so do not have release branches or tags. Other projects (e.g. terraform manifests) may use environment branches rather than release branches.