Branching strategy

Note

Please read about branching strategy in general and repository management first.

Depending on the complexity and the release cycle of the project choose one of the following two branching strategies: GitHub-Flow or Git-Flow.

Git Flow

Git Flow is an advanced branching strategy which has the capability to support a software with longer release cycle, multiple versions and environments.

This branching strategy consists of the following branches:

  • Main: always reflects a production-ready state.
  • Develop: always reflects a state with the latest delivered changes for the next release.
  • Feature: to develop new features that branches off the develop branch.
  • Release: help prepare a new production release, usually branched from the develop branch and must be merged back to both develop and master.
  • Hotfix: also helps prepare for a release but unlike release branches, hotfix branches arise from a bug that has been discovered and must be resolved. It enables developers to keep working on their own changes on the develop branch while the bug is being fixed.

Git flow

When to choose Git Flow

Consider below pros and cons before choosing Git Flow as branching strategy.

Pros

  • Allow team to work on multiple releases in parallel.
  • Provides clear version control as each release is tagged.
  • Allows multiple developers to work on the same feature by committing incomplete parts to develop or branching off of a feature branch.

Cons

  • Many branches to maintain.
  • Technical dept can build-up due to the overhead required to release.

Implementation

  • At the beginning of the project a main branch is created first and left empty, maybe apart from a README.md and a .gitignore file.
  • A develop branch is immediately branched off of main. No changes are ever made directly to main or develop.
  • Developers branch off of develop into a feature branch to make their changes. Changes from develop will occasionally need to be merged into the feature branch depending on how long it takes to develop the feature.
  • Once a change is done a pull request (PR) is created so that the team can review the change before it is merged into develop.
  • Once all the work for the release has been done a release branch is branched off of develop.
  • If an issue is found with the release then a branch is created off of the release branch to work on the fix. This is then applied to the release branch once it has been reviewed.
  • When it comes to releasing, releases are created from the release branch and changes merged into main and develop. Release must be tagged on main.
  • If there is a production issue after a release then a hotfix branch is created off of the main branch in order to apply the fix.

GitHub Flow

GitHub flow is a lightweight strategy, ideal for projects with short release cycle. When a feature or a fix is ready to go, it can be deployed. Features and fixes handled similarly.

GitHub flow

This branching strategy consists of the following branches:

  • Main: always reflects a production-ready state.
  • Feature: to develop new features that branches off directly of main branch.

When to choose GitHub Flow

Consider below pros and cons before choosing GitHub Flow as branching strategy.

Pros

  • Clear and simple.
  • Encourages fast feedback loops, making it possible to quickly identify issues and make changes.
  • Quick release cycle.
  • Small changes reduces the risk of technical debt.

Cons

  • Speed comes at the cost of comprehensiveness and may make it harder to manage the overall development process.
  • The main branch can become cluttered more easily since it functions as both the production and development branch. Release preparation and bug fixes both happen in this branch — and require extra attentiveness.

Implementation

Change request

  • Main branch contains the latest working version that can be deployed.
  • To implement a task, a new branch is created from the main following naming convention.
  • Commit changes to the local branch frequently and synchronize them to the remote branch regularly.
  • To merge changes into main initiate a pull request to request code review.
  • Changes must be deployed to test environment for verification from the feature branch
  • After code review and verification are passed, code can be merged into main.
  • Release package is created from the main branch.

Hotfix

  • If a defect is found after a release, a hotfix branch is created from the commit version that is deployed to prod of main branch
  • Defect is corrected and verified on the hotfix branch
  • Fix is merged into main and deployed to production.

Branch policies

Regardless of the chosen branching strategy it is highly recommended to protect the main branch. When working on a .NET project, apply below policies to the main branch:

  • Main branch can be updated only via pull requests.
  • At least one other team member has to review and approve a pull request to be merged into main.
  • Pull requests must be linked to work items.
  • All comments need to be resolved on pull requests.
  • Limit merge types to Squash merge and Rebase with merge commit to keep clean the history of main branch.
  • Pull requests must be validated be CI build.