Branching Strategy

Source: Confluence - Branching Strategy

Overview

A branching strategy is the approach that software development teams adopt when writing, merging, and deploying code when using a version control system (VCS). It is essentially a set of rules that developers can follow to stipulate how they interact with a shared codebase.

Adhering to a branching strategy will:

• Keep repositories organized
• Assist with merging code bases
• Allow developers to work together without stepping on each other’s toes
• Enable teams to work in parallel for faster releases and fewer conflicts

Git and Bitbucket

• VCS: Git
• Remote Repository: Bitbucket - Path2Response
• origin: Shorthand for the remote repository (source of truth)

Branching Strategies Overview

Path2Response’s branching strategy draws from the best of common strategies:

1. GitFlow
2. GitHub Flow
3. GitLab Flow
4. Trunk-based development

Path2Response Branching Strategy

Main Branch

The primary code base is the main branch.

• origin/main is where HEAD reflects our current code base
• Represents what is intended to be in production (not necessarily what is deployed)
• All deployments to production are generated from this branch
• Reflects a state with the latest delivered development changes for the next release

Note: Historically the default was master, now it’s main.

Feature Branch

Feature branches allow developers to work together without constant merge conflicts.

Naming Convention: Use the Jira issue key (e.g., PATH-1234)

Guidelines:

• All development should be done on feature branches
• No development directly on main
• Commit code to the feature branch constantly
• Push to origin when ready (at end of development for solo work)
• Routinely pull main and merge into your feature branch (at least daily for multi-day features)
• We do not rebase our branches - just merge and keep individual commits intact

Feature branches are temporal:

• Typically don’t exist longer than a sprint or two
• Delete after cleanup period (after one sprint post-release)

Epic Branches: For complex work spanning multiple sprints:

1. Work for each issue under Epic is done on the Epic branch, or
2. Work for each issue is done on its own feature branch, then merged into Epic branch

Development Branch

The dev branch is where work from feature branches is placed for testing in an isolated development environment.

Note: Currently, the dev branch does not exist in our repositories. This will change in the near future.

Purpose:

• Test features in isolation before integration
• Alternative to serverless: feature branch deployed to its own environment

Staging Branch

The staging branch is where all code (typically from all feature branches) is placed for integration testing during a sprint.

Purpose:

• First opportunity for integration testing across developers
• Can expose problems when two feature branches work in isolation but break together
• Intended for developers (not stakeholders)

Current State: We are using staging for acceptance. This will change when projects move to serverless.

Acceptance Branch

The acceptance branch contains code to be reviewed and (hopefully) accepted by stakeholders.

Note: Currently, the acceptance branch does not exist and there is no acceptance environment. This will change in the near future.

Tag for Release

At the completion of each sprint, the code on main is tagged with the sprint version.

Tag Format: 249.0.0 (sprint number followed by .0.0)

What happens:

1. Commit to main updates the version to the official sprint version
2. Tag is created referencing that commit
3. All work for the next sprint includes code from the tagged state

Production Branch

The production branch provides clear separation between the primary code base and the production environment.

Advantages:

1. Clear code base representing what is on the production environment
2. Enables CI/CD using the production branch for continuous delivery

Access: Merging to production is restricted and not available to most developers.

Release Candidate Branch

The release_candidate branch is where code is merged to for pre-release testing.

Environment: “rc” (release candidate environment)

Note: “release candidate” for branch name, “rc” for environment to avoid confusion.

Sprint Release Activities

Reset Branches

At the start of each sprint, branches are reset to the previous sprint’s tag:

• dev, staging, acceptance, and release_candidate are reset to the previous sprint’s tag
• Versions are then set to 250.0.0-SNAPSHOT (indicating temporal snapshot leading to release)

Sprint Release Process

During Development Sprint Planning:

1. Tag Release - Tag main with sprint version
2. Set Pre-Release Versions - Update version numbers
3. Reset Staging Branches - Reset all branches from the tag

Sprint Timeline:

1. Sprint Retrospective → branches/environments reset
2. Pre-release testing on rc environment
3. Production approval from Production team
4. Sprint tag pushed to production and deployed

Hotfix and Patch Process

Hotfix Branch

For issues requiring immediate resolution that can’t wait for the next sprint release.

Creation:

• Create from main that was deployed to production
• Named after the Jira issue (e.g., PATH-1235)

Testing Hot Fix

1. If bug can be isolated, merge hotfix branch to dev and deploy to development environment
2. Be careful: sprint code may not match production, creating testing challenges

Patch Branch

The patch branch manages and deploys the hotfix to production.

Important: Created from the last tag deployed to production, NOT from main or production.

Naming Conventions:

1. patch_{Tag Version} (e.g., patch_250.1.0)
2. patch_{Jira Issue}_{Intended Patch Version} (e.g., patch_PATH-1235_250.1.0)

Version name must match across patch branch, internal version, and tag.

Patch Workflow

1. Cherry-pick commits from hotfix branch to patch branch (don’t merge entire branch)
2. Update version information on patch branch
3. Create pull requests for both feature branch (to main) and patch branch (to production)
4. Tag the patch using annotated tags
5. Deploy from the tag to production
6. Merge fix to main - hotfix branch goes through normal PR and acceptance process

Summary

Key Principles

1. Never develop directly on main
2. Name branches after Jira issues
3. Merge main into feature branches regularly (at least daily)
4. Don’t rebase - just merge
5. Patches come from tags, not main
6. Cherry-pick hotfixes to patches, don’t merge entire branches
7. Use annotated tags for releases