Branching Strategies¶

This document outlines two recommended branching strategies for use with this template.

The choice of strategy depends on whether the project produces a single application artifact or multiple components deployed across several environments.

Single-Component¶

This is the default branching strategy used in this template:

Tip

This strategy is best suited to single-component projects or projects with a single deployment environment (i.e. a singular Python package/library maintained in a dedicated repository).

It is a simplified version of GitHub Flow.

---
title: Branching strategy (GitHub Flow)
config:
  theme: 'dark'
---
gitGraph TB:


  %% Production branches:

  checkout main
  commit tag: "v1.0.4"


  %% Feature branches:

  checkout main
  branch "feature/a"
  commit tag: "v1.1.0 [pre-release]"
  commit tag: "v1.1.1 [pre-release]"
  commit tag: "v1.1.2 [pre-release]"

  %% Release:

  checkout main
  merge "feature/a" type: REVERSE id: "MERGE"
  commit tag: "v1.1.2 [release]"

  %% New feature:
  checkout main
  branch "feature/b"
  commit tag: "v1.2.0 [pre-release]"
  commit tag: "v1.2.1 [pre-release]"
  commit tag: "v1.2.2 [pre-release]"

This strategy relies on two primary branches:

main
feature/*

Note

Commits to feature/* branches trigger pre-release pipelines, deploying artifacts to test environments (e.g., test.pypi.org).
Merging into main triggers full release pipelines, deploying artifacts to production (e.g., upload.pypi.org).

Multi-Environment¶

This is a modified GitFlow strategy using long-running branches for each environment:

Tip

This strategy can be simplified where there is high automation and comprehensive test coverage.

In these cases, separate integration and testing environments may be unnecessary under a "continuous deployment" lifecycle where each validated change goes directly to production.

Environment	Branch	Change Controls	Description
Production	main	FULL	Represents the live, customer-facing production environment.
Staging	staging	HIGH	Pre-production replica of `production` used for User Acceptance Testing (UAT).
Testing	testing	LOW	Initial environment equipped for QA and performance testing.
Integration	integration	NONE	Development environment for integrating components, CI/CD pipelines, IaC, and test suites.

Note

New feature/* branches are first merged into integration and testing, triggering their respective deployments.
After testing, features are promoted to staging and tagged as release candidates.
Fixes are handled via bugfix/* branches, merged back into staging and lower environments as needed.
The stable release tag is finally promoted to production.

---
title: Branching strategy (multi-env, multi-component)
config:
  theme: 'dark'
---
gitGraph TB:


  %% Production branches:

  checkout main
  commit tag: "v1.0.6"
  commit tag: "v1.1.4"

  branch staging
  %%commit


  %% Integration branches:

  branch testing
  %%commit

  branch integration
  %%commit


  %% Feature branches (off `staging`):

  checkout integration
  branch "feature/a"
  commit

  checkout integration
  branch "feature/b"
  commit


  %% Release branch:

  checkout integration
  branch "release/x"


  %% Merging "feature/" branches:

  checkout integration

  merge "feature/a" type: REVERSE id: "MERGE [1]"
  commit id: "deploy (integration) [1]"

  merge "feature/b" type: REVERSE id: "MERGE [2]"
  commit id: "deploy (integration) [2]"

  checkout testing
  merge integration type: REVERSE id: "MERGE [3]"
  commit id: "deploy (testing) [1]"

  checkout "release/x"
  merge testing type: REVERSE id: "MERGE [4]"

  commit id: "deploy (staging) [1]" tag: "v1.2.0"


  %% Bugfixes:

  checkout "release/x"
  branch "bugfix/a"
  commit

  checkout "release/x"
  branch "bugfix/b"
  commit

  checkout "release/x"

  merge "bugfix/a" type: REVERSE id: "MERGE [5]"
  commit id: "deploy (staging) [2]" tag: "v1.2.1"

  merge "bugfix/b" type: REVERSE id: "MERGE [6]"
  commit id: "deploy (staging) [3]" tag: "v1.2.2"


  %% Tag creation:

  checkout "release/x"
  commit id: "release" tag: "v1.2.3"


  %% Branch alignment:

  checkout integration
  merge "release/x" type: REVERSE id: "MERGE [7]"

  checkout testing
  merge "release/x" type: REVERSE id: "MERGE [8]"


  %% Pre-release:

  checkout staging
  merge "release/x" type: REVERSE id: "MERGE [9]"


  %% Release:

  checkout main
  merge staging type: REVERSE id: "MERGE [10]"
  commit id: "deploy (production) [1]"


  %% Hotfix:

  branch "hotfix/x"
  commit

  checkout main
  merge "hotfix/x" type: REVERSE id: "MERGE [11]" tag: "v1.2.4"
  commit id: "deploy (production) [2]"

  checkout staging
  merge main type: REVERSE id: "MERGE [12]"

  checkout testing
  merge main type: REVERSE id: "MERGE [13]"

  checkout integration
  merge main type: REVERSE id: "MERGE [14]"

Caution

This strategy assumes staging accurately replicates production, allowing you to address issues via bugfix/* branches prior to production deployment.

If issues are discovered after release, deploy fixes by branching hotfix/* directly from main. This creates a new patch release tag for production.

After validation, merge main back into all lower environments to keep them synchronized.