Skip to content

3. Branching & Version Control
What The branching model, naming conventions, and rules for organizing all code changes.
Owner Engineering (every developer), enforced by branch protection and review.
Triggers At the start of every release cycle and for every individual task.

Summary

We use a release-branch model derived from the widely adopted Git Flow approach. There are permanent branches (master for production-ready code, develop for integrated work) and temporary branches (release/* and hotfix/*) for controlled delivery. All actual work happens on feature/* and bug/* branches that flow in through pull requests. Nothing is ever committed directly to a protected branch. Every release branch name matches its JIRA Release version exactly, so code, tracking, and deployments always line up.

Full detail

The branches

Branch Type Purpose
master permanent Production-ready code. Always deployable.
develop permanent Latest integrated development work.
release/<version> temporary A controlled release in progress (for example release/v1.3.0). The version MUST match the JIRA Release version.
hotfix/<version> temporary Urgent production fix (for example hotfix/v1.3.1).
feature/<ticket> working A single feature or task (for example feature/ABC-1234).
bug/<ticket> working A single bug fix (for example bug/ABC-1234).

If a feature genuinely has no ticket (rare and discouraged), use a short descriptive name: feature/short-feature-name.

Branch creation rules

Normal release work:

  1. Create the release branch from develop: develop becomes release/<version>.
  2. Create feature and bug branches from the release branch: release/<version> becomes feature/<ticket>.

Bug fixes found by QA during testing (release already built and frozen): branch the fix from that same release branch: release/<version> becomes bug/<ticket>. See Defect Handling.

Hotfixes for production: branch from the last production tag, not from develop. See Hotfix.

gitGraph
    commit id: "develop"
    branch release/v1.3.0
    checkout release/v1.3.0
    commit id: "cut release"
    branch feature/ABC-1234
    checkout feature/ABC-1234
    commit id: "build feature"
    checkout release/v1.3.0
    merge feature/ABC-1234 tag: "PR merged"
    branch bug/ABC-1240
    checkout bug/ABC-1240
    commit id: "QA fix"
    checkout release/v1.3.0
    merge bug/ABC-1240 tag: "PR merged"
    checkout main
    merge release/v1.3.0 tag: "v1.3.0"

Hard rules

These are MUST rules, enforced by branch protection where the platform allows:

  • Never commit directly to develop, release/*, master, or hotfix/*.
  • All commits reach those branches only through feature/* or bug/* branches and a reviewed pull request.
  • Every task, bug, or enhancement has its own dedicated branch.
  • Release branches stay stable and controlled. Only one release branch should ideally be active at a time.

Versioning

We follow Semantic Versioning: MAJOR.MINOR.PATCH. Each release branch has a unique version. Hotfixes increment the patch number (v1.3.0 becomes v1.3.1). A release branch is tagged only after all work is integrated and approved, never before.

Example

The sprint's JIRA Release is v1.4.0. A developer cuts release/v1.4.0 from develop, then branches feature/ABC-1310 off the release branch for their assigned story. When done, they open a PR back into release/v1.4.0. They never touch develop or master directly. When QA later finds an issue, the fix goes on bug/ABC-1325 cut from release/v1.4.0, not from a fresh develop.