Branching Strategy

Article: Dec 17, 2024

Effective branching strategies are crucial for managing code, enabling collaboration, and ensuring smooth deployments. This document outlines a recommended branching strategy and provides alternative options to cater to various project needs.

This strategy balances simplicity with flexibility, ensuring a structured approach to feature development, testing, and releases:

Main Branch

  • Contains the latest, reviewed code changes that are ready for testing.
  • All completed features, and fixes are merged here via pull requests (PRs).
  • Branch serves as the central hub for stable, deployable code.
  • Serves as the base branch for creating release/test/*branches.

Feature Branches

Naming convention: feature/<scope>/<identifier or description>

  • Purpose: Used for development work on new features, bug fixes, or enhancements.
  • Temporary: These branches are merged into main via PRs and deleted after completion.

Example: feature/authentication/oauth2-support

Test Release Branches

Naming convention: release/test/<release-id>

  • Purpose: To prepare and validate changes in a testing or User Acceptance Testing (UAT) environment. These branches must remain stable and isolated to support extended testing cycles when necessary.
  • Usage: Changes merged into these branches should be verified and meet the minimum branching criteria before being considered production-ready.

Example: release/test/2024-12-01

Production Release Branches

Naming convention: release/production/<release-id>

  • Purpose: Dedicated to deploying changes to the production environment.
  • Created from release/test/* branch after successful testing and review.

Example: release/production/2024-12-01

Hotfix Release Branches

Naming convention: release/hotfix/<hotfix-id>

  • Purpose: Reserved for urgent fixes that bypass the usual feature and release cycle.
  • Usage: Hotfix branches should isolate critical changes from active development and testing to ensure a clean and quick path to production deployment.

Example: release/hotfix/2024-12-01-critical-issue

Key Considerations

When adopting this branching strategy, consider the following:

Minimum Branching Criteria

To ensure code quality, isolation, and maintainability, the following minimum criteria should be adhered to:

  • Isolation of untested development code: Code that is still under development must be separated from branches intended for testing or production.
  • Isolation of in-development code from test-eligible code: Development branches (feature/*) should not be merged into testing branches until feature work is complete and validated.
  • Isolation of in-test code from production code: Test release branches (release/test/*) must isolate changes from production-ready branches to avoid premature deployment.
  • Support for Long Functional Testing Cycles: Stabilized test branches allow extended testing periods without impacting ongoing development.

Pull Requests and Reviews

  • All changes must go through a PR for code review to ensure quality and maintainability.
  • Use automated checks, such as CI pipelines, for consistent code validation.

Consistent Naming Conventions

  • Follow the naming patterns strictly for clarity and standardization.
  • Use descriptive identifiers that communicate the purpose of the branch.

Branch Lifetime

  • Keep feature branches short-lived to avoid merge conflicts.
  • Regularly clean up merged or stale branches.

Deployment Pipeline Integration

Align the branch structure with CI/CD pipelines to enable specific scenarios:

  • Developer isolation of features: Prevent incomplete or unstable features from progressing to production by using dedicated feature/* branches.
  • Stabilized test branches: Maintain stabilized release/test/* branches for UAT and SIT scenarios, ensuring extended testing cycles when required.
  • Hotfix branches: Support urgent fixes through isolated release/hotfix/* branches that expedite production deployment without affecting ongoing work.

Alternative Branching Options

Projects with different requirements may benefit from alternative approaches:

Option 1: GitFlow

Branches (GitFlow)

Main

  • Contains production-ready code.
  • Represents the deployment point for all releases.
  • Never contains unfinished or experimental code.

Develop

  • Serves as the integration branch for all features.
  • Contains the latest development changes that are still under validation.
  • Features are merged here via pull requests.

Feature Branches

  • Created from develop for individual features, bug fixes, or enhancements.
  • Merged back into develop via pull requests.
  • Naming convention: feature/<scope>/<description>.
  • Example: feature/authentication/oauth2-support.

Release Branches

  • Created from develop when a release is ready for testing and stabilization.
  • Allows final bug fixes, release notes preparation, and UAT.
  • Merged into both main (to deploy) and develop (to integrate post-release fixes).
  • Naming convention: release/<version>.
  • Example: release/1.2.0.

Hotfix Branches

  • Created from main for urgent fixes that bypass the usual development flow.
  • Merged into both main (to deploy) and develop (to prevent regressions).
  • Naming convention: hotfix/<version>-<description>.
  • Example: hotfix/1.2.1-critical-bug.

Pros (GitFlow)

Clear separation of development, testing, and production.

Cons (GitFlow)

Overhead in managing additional branches.

Option 2: Trunk-Based Development

Branches (Trunk-Based)

  • main (single, continuous integration branch)
  • Short-lived feature branches

Pros (Trunk-Based)

Encourages rapid integration and delivery.

Cons (Trunk-Based)

Requires robust CI/CD to ensure stability.

Option 3: Release-Only Branching

Branches (Release-Only)

  • main
  • release/* (for specific releases)

Pros (Release-Only)

Simple and minimalistic.

Cons (Release-Only)

Less flexibility for parallel development efforts.

Choosing the Right Strategy

Consider the following factors when selecting a branching strategy:

  • Team Size: Larger teams may benefit from more structured branching, while smaller teams can adopt simpler approaches.
  • Release Cadence: Fast-moving projects may prefer shorter branch lifetimes.
  • Tooling and Automation: Ensure your CI/CD pipelines support the chosen branching model.
  • Collaboration Needs: Highly collaborative environments may need additional review processes and branch management.

By understanding these options and their trade-offs, teams can adopt a strategy that aligns with their goals and workflows.