Table of Contents

Git flow

The git flow defines how to integrate a build and release strategy with the git source control management (SCM).

Overview

Following git flow style, there are three types of branches: main, feature and release branches.

Depending on the branch, pushing a commit or a git tag may trigger a deployment pipeline (shown as a tag in the diagram):

  • Dev: no deployment, just local dev builds and PR build validations.
  • Preview: software ready for deploying in the preview environment. Automatically on every push (e.g., pull-request merge) or manually (e.g., end of Agile sprint).
  • Production: promotion of the deployment to the production environment. Usually after pushing a git tag or approving the validation task.
---
title: "Git flow"
config:
  theme: base
  gitGraph:
    showCommitLabel: false
    mainBranchOrder: 2
---

gitGraph LR:
  commit tag: "Preview"

  %% Feature into main
  branch feature/work1 order: 1
  commit tag: "Dev"
  commit tag: "Dev"
  checkout main
  merge feature/work1 tag: "Preview"

  %% Create release branch
  branch release/X.Y order: 3
  commit tag: "Preview (RC)"

  %% In parallel, new features to main
  checkout main
  branch feature/breaking order: 0
  commit tag: "Dev"

  %% Fix after quality assurance tests
  checkout release/X.Y
  branch feature/qa-fix order: 4
  commit tag: "Dev"

  %% After the merge, more testing and approval -> release to prod
  checkout release/X.Y
  merge feature/qa-fix tag: "Preview (RC) -> Production (vX.Y.Z)"

  %% More work on the dev feature
  checkout feature/breaking
  commit tag: "Dev"
  checkout main
  merge feature/breaking tag: "Preview"

  %% Merge release branch
  checkout main
  merge release/X.Y tag: "Preview"

  %% Patch release for latest release
  checkout release/X.Y %% in practice, branch from the git tag name
  branch feature/hotfix order: 5
  commit tag: "Dev"
  checkout release/X.Y
  merge feature/hotfix tag: "Preview (RC) -> Production (vX.Y.Z + 1)"

  %% Merge hotfix to main as cherry-picks from now on
  %% The hotfix may happen a long time after the release that merging directly
  %% to main may be difficult, and not all fixes may be required.
  %% Cherry-picking may simplify the process of adapting to the current codebase.
  checkout main
  commit type: HIGHLIGHT tag: "cherry-pick hotfix - Preview"

Main branch

Also known as develop or dev, it's the current development branch with latest features and fixes.

This branch should be protected so no direct pushes are allowed. Changes should come via pull requests from feature branches.

Pushing in this branch new comments will trigger a new preview build type. This means that artifacts are deployed to the preview / staging feeds. This will only happens when a pull request is merged.

Note

If you are working on a small, personal project alone, it should be fine not using pull requests and pushing directly.

Feature branches

Development branches for small features and bug fixes.

They are prefixed with feature/ for all type of work (including bug fixes). This simplifies the configuration of tools (like GitVersion) and gives consistency in the branching schema.

Building locally or in pull requests creates a development build. No artifacts are deployed, but they should be accessible to download and test from CI output.

Tip

Merging pull requests with the squash strategy could be a good idea as it keeps a clean git history. The only exception is the first merge from the release branch into the main.

Release branches

Branches that help with the release and support process of a product release. In a release branch you can stabilize the release without stopping development in the main branch of new features that won't go into that release. This is the case when stablishing a code freeze or feature freeze date, from which no more development is allowed without previous approval.

They are prefixed with release/ followed by the major and minor version numbers.

Pushing changes into a release branch should happen only via pull requests that are carefully reviewed. A new commit will trigger a new preview build.

Once the release is ready, stakeholders would signs-off / approve the release and its quality assurance results. This approval is transformed into a new git tag to the latest commit. Pushing a tag will trigger a new production build.

After the release is out, a release (also known as support) branch can be used to work on regular patch release like for long-term support (LTS) versions. Otherwise, remove them as they do not offer any advantage. You can always re-create it from the latest git tag.

Note

In a small, personal projects you most likely won't need these branches. Just tag directly main, for instance by creating a GitHub release. You can always check-out a tagged commit, branch and create a patch release from there if needed.

Epic branches

Special type of a development branch. It helps to implement large features that could affect the development of other current features.

It acts as a temporary parallel branch to main. Feature branches related to the feature are merged into the epic. Once the feature is stable enough, the epic is merged into the main branch as it were a big feature branch.

Try to minimize the usage of epic branches to prevent huge merge conflicts later.

Note

This schema does not use a master branch as the original git flow proposed. This branch has not much use. It's possible to get the latest stable version by listing git tags. Not having the branch prevents typical issues with the merges and conflicts.

Edit this page