Policy: Git Branching & Merge Strategy

Purpose

To define a standardized branching and merge strategy for all repositories, ensuring clean history, safe releases, and predictable collaboration.

Scope

  • Applies to all repositories (backend, frontend, mobile, shared libraries).
  • Used by all developers and leads.
  • Covers branch naming, merge rules, and protection policies.

Principles

  1. Clarity – Branch names must clearly indicate purpose and linked ticket.
  2. Stability – main (or master) always represents a deployable production state.
  3. Traceability – All commits must trace back to a ticket or documented change.
  4. Collaboration – PR reviews are mandatory before merge.
  5. Consistency – All projects must follow this strategy unless an exception is approved.

Branching Rules

Primary Branches

BranchPurposeRules
mainProduction-ready codeProtected, only merged via PR with approvals
developIntegration branch for featuresStaging builds; PR merges only
release/*Pre-production stabilizationBug fixes, final QA, version bump

Supporting Branches

TypeNaming ConventionPurposeExample
Featurefeature/<ticket-key>-<slug>New featuresfeature/WEB-142-export-csv
Bugfixbugfix/<ticket-key>-<slug>Non-hotfix bugbugfix/API-88-login-500
Hotfixhotfix/<ticket-key>-<slug>Urgent prod fixhotfix/BUG-301-null-ref
Spikespike/<ticket-key>-<slug>Research/POCspike/ARCH-12-ratelimit
Chorechore/<ticket-key>-<slug>Non-functional taskchore/DEV-19-upgrade-node

Merge Rules

Pull Requests

  • PRs required for all merges.
  • Must include:
    • Ticket link (Jira/ClickUp).
    • Clear description (what/why).
    • Testing notes (unit, integration, manual).
  • PR Template (auto-populated per repo).

Approvals

Change TypeRequired Approvals
Small (≤200 LOC)1 peer reviewer
Medium (200–600 LOC)1 peer + Tech Lead
Large (>600 LOC)2 peers + Tech Lead
Critical (security, infra)Tech Lead + Security/DevOps

Merge Strategy

  • Default: Squash and merge (clean history).
  • Alternative (monorepos): Merge commit if needed for dependency tracking.
  • Hotfixes: Cherry-picked into main → back-merged into develop.

Protected Branch Rules

  • No direct commits to main or develop.
  • CI checks (lint, tests, build) must pass before merge.
  • Feature branches auto-deleted post-merge.

Governance

  • Enforcement: Branch protection rules enforced at repo level.
  • Audit: Quarterly audit of merge history for compliance.
  • Exceptions: Must be approved by Tech Lead + CTO.
  • Training: All new devs trained during onboarding (EPIC 1 – Doc 1).