Skip to content

BRANCHING_STRATEGY.md

Latest commit

 

History

History
391 lines (313 loc) · 15.5 KB

BRANCHING_STRATEGY.md

File metadata and controls

391 lines (313 loc) · 15.5 KB
file_type documentation
title Org-wide Git Branching Strategy
description Canonical branch naming, protection, merge discipline, and automation rules for LightSpeedWP repositories.
last_updated 2026-06-09
owners
LightSpeed Team
version v1.5
status active
stability stable
domain governance
tags
branching
git
governance
ci
language en

Org-wide Git Branching Strategy

Primary operations reference: GITHUB_PROJECT_OPERATIONS_SPEC.md

changelog issues labeling linting meta metrics planner project-meta-sync release reporting reviewer testing

Keep main always deployable, reduce merge risk, and make PR automation predictable across all LightSpeedWP repositories. This policy aligns branch names with Issue Types and Projects, powers label and workflow automation, and enforces disciplined merge practices.

1. High-level Rules

  • main is production-ready at all times.
  • Optional develop branch for integration workflows.
  • Short-lived branches; open PRs early and keep changes small.
  • Squash merge to preserve linear history; delete branches post-merge.
  • Use branch prefixes that map cleanly to Issue Types and Project fields.

2. Branch Protection

Apply these GitHub protection rules to main (and develop if used):

  • Require pull request before merging.
  • Require approvals: 1 for most repos, 2 for critical repos.
  • Require review from Code Owners (if using CODEOWNERS).
  • Dismiss stale approvals when new commits are pushed.
  • Require conversation resolution before merging.
  • Require status checks to pass before merging (lint, tests, build).
  • Require branches to be up to date before merging.
  • Require linear history (squash-merge only).
  • Do not allow bypassing (include administrators).
  • Optionally require signed commits.

Enable squash merge only; disable merge commits and rebase merges.

3. Branch Naming

Format: {type}/{scope}-{short-title} Use lower-case, kebab-case, and keep it short.

3.1 Required Core Prefixes

For all repos (client, product, infra, etc.), use:

  • feat/ — new capability/feature
  • fix/ — bug fix
  • hotfix/ — urgent production fix
  • release/ — release branches (e.g., release/v1.6.0)
  • refactor/ — internal restructure
  • chore/ — maintenance, housekeeping
  • docs/ — documentation
  • test/ — testing only
  • perf/ — performance improvements
  • ci/ — CI/CD or workflow changes
  • build/ — build process changes
  • deps/ — dependency updates
  • security/ — security-related
  • revert/ — revert previous changes
  • research/ — research spikes
  • design/ — design changes
  • a11y/ — accessibility changes
  • ux/ — user experience
  • i18n/ — internationalization
  • ops/ — operations

3.2 Optional Product Profile Prefixes

  • proto/ — prototypes/experiments
  • ds/ — design system
  • api/ — API surface
  • schema/ — DB/schema changes
  • telemetry/ — analytics/metrics

3.3 Optional Client Profile Prefixes

  • content/ — content edits, redirects, IA
  • seo/ — SEO, metadata, schema, sitemap, robots
  • config/ — site/plugin configuration
  • migrate/ — data/content migrations
  • qa/ — test harnesses, UAT scaffolding
  • uat/ — UAT-only changes or staging toggles
  • codex/ — Codex-assisted work branches used by the local agent workflow

3.4 Examples

feat/product-grid-quick-add
refactor/split-frontend-bundle
api/orders-bulk-cancel
schema/add-index-orders-created
telemetry/add-checkout-step-events
release/v1.6.0
hotfix/cart-csrf-check

fix/nl-postcode-validation
content/category-copy-refresh
config/feature-flags-cart
seo/add-faq-schema-on-product
release/go-live-2025-10-10
hotfix/ga4-purchase-duplicate

4. Branch Name Enforcement via CI

4.1 Human and Agent Branch Discipline

  • Validate branch relevance before the first edit.
  • If the current branch belongs to a different issue, PR, or task, create a new branch from develop before making changes.
  • Do not reuse in-flight branches for unrelated work, even when the working tree is already open.
  • If unrelated local changes are present, use a clean worktree rather than mixing scopes.
  • Temporary audit replay branches created for PR merge prep may use the form pr-<number>-audit when they need to keep a live PR attached to a historical review branch.

Use a single regex in a workflow to enforce naming discipline:

^(feat|fix|hotfix|release|refactor|chore|docs|test|perf|ci|build|deps|security|revert|research|design|a11y|ux|i18n|ops|proto|ds|api|schema|telemetry|content|seo|config|migrate|qa|uat|codex)/[a-zA-Z0-9._-]+$

Example workflow (.github/workflows/validate-branch-name.yml):

name: Validate branch name
on:
  pull_request:
    types: [opened, reopened, synchronize, edited, ready_for_review]
jobs:
  check-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Enforce {type}/{scope}-{short-title}
        run: |
          BRANCH="${{ github.head_ref }}"
          # Allow dependabot/renovate
          if [[ "$BRANCH" =~ ^(dependabot|renovate)/ ]]; then exit 0; fi
          # Allow temporary audit replay branches used for PR merge prep
          if [[ "$BRANCH" =~ ^pr-[0-9]+-audit$ ]]; then exit 0; fi
          if [[ ! "$BRANCH" =~ ^(feat|fix|hotfix|release|refactor|chore|docs|test|perf|ci|build|deps|security|revert|research|design|a11y|ux|i18n|ops|proto|ds|api|schema|telemetry|content|seo|config|migrate|qa|uat)/[a-zA-Z0-9._-]+$ ]]; then
            echo "❌ Branch '$BRANCH' must match the required pattern."
            exit 1
          fi

[NEW]

  • For monorepos, ensure branch naming applies to each package/subproject, or use a consistent prefix (e.g. feat/frontend-..., fix/api-...).
  • For forked repos, always clean up branches after merging upstream PRs, and avoid duplicating branch names across forks to prevent confusion.

5. Prefixes Drive Automation

5.1 Labeler (Status Kick-off)

Ensure .github/labeler.yml seeds new PRs with status:needs-review when appropriate:

"status:needs-review":
  - head-branch:
      [
        "^feat/.*",
        "^fix/.*",
        "^hotfix/.*",
        "^release/.*",
        "^refactor/.*",
        "^chore/.*",
        "^docs/.*",
        "^test/.*",
        "^perf/.*",
        "^ci/.*",
        "^build/.*",
        "^deps/.*",
        "^security/.*",
        "^revert/.*",
        "^research/.*",
        "^design/.*",
        "^a11y/.*",
        "^ux/.*",
        "^i18n/.*",
        "^ops/.*",
        "^proto/.*",
        "^ds/.*",
        "^api/.*",
        "^schema/.*",
        "^telemetry/.*",
        "^content/.*",
        "^seo/.*",
        "^config/.*",
        "^migrate/.*",
        "^qa/.*",
        "^uat/.*",
      ]

[NEW]

  • For automation, use GitHub Actions to auto-assign reviewers based on branch type (e.g., security → security lead).
  • Sync project automation rules across all repos using .github repo templates.

5.2 Project Type Mapping

Extend your project sync workflow so branch prefixes set the Project Type field:

  • feat/ → Feature/Story
  • fix/ → Bug (hotfix → critical Bug)
  • refactor/ → Refactor
  • chore/, ci/, build/, deps/, security/ → Chore
  • design/, a11y/, ux/ → Design/Task
  • content/, seo/, config/, migrate/, qa/, uat/ → Task/Operations
  • proto/, api/, schema/, telemetry/, ds/ → Feature/Task
  • release/ → Release PR

Principle: Labels remain routing signals (status, priority, area/component). Issue Types and Project fields carry the semantic meaning.

5.3 PR Template Routing

Use .github/PULL_REQUEST_TEMPLATE/config.yml as the canonical machine-readable route map, and keep it aligned with the branch names and template files below. Where there is no specialised template file, the closest active template is reused so automation stays predictable.

Branch prefix PR template
feat/ pr_feature.md
fix/ pr_bug.md
hotfix/ pr_hotfix.md
refactor/ pr_refactor.md
chore/ pr_chore.md
docs/ pr_docs.md
test/ pr_chore.md
perf/ pr_feature.md
ci/ pr_ci.md
build/ pr_ci.md
deps/ pr_dep_update.md
security/ pr_bug.md
design/ pr_feature.md
a11y/ pr_feature.md
ux/ pr_feature.md
release/ pr_release.md
research/ pr_feature.md
revert/ pr_chore.md
i18n/ pr_feature.md
ops/ pr_chore.md
proto/ pr_feature.md
ds/ pr_feature.md
api/ pr_feature.md
schema/ pr_feature.md
telemetry/ pr_feature.md
content/ pr_docs.md
seo/ pr_docs.md
config/ pr_chore.md
migrate/ pr_chore.md
qa/ pr_chore.md
uat/ pr_chore.md

6. Merge Discipline

  • Keep branches current; resolve all conversations before merging.
  • Squash merge only; PR title becomes the squash commit.
  • Delete the branch after merge. [NEW]
  • Never force push to shared branches (main, develop); use protected branch settings.
  • For remote teams, always communicate in PR comments and reference related issues for traceability.

7. Release & Hotfix Flow

  • Release: Open release/vX.Y.Z, bump versions and changelog, run full CI, QA on staging, merge to main, tag, deploy.
  • Hotfix: Branch from main as hotfix/<slug>, minimal fix, PR to main, tag, cherry-pick/back-merge to develop (if used). [NEW]
  • Always update release notes and changelog for each release/hotfix, even when changes seem minor.

8. Quick Per-Repo Checklist

  • Enable branch protections on main (+ develop if used).
  • Adopt branch naming discipline; enforce via CI workflow.
  • Sync .github/labeler.yml and project mapping with chosen prefixes.
  • Prefer Issue Types and Project fields over proliferation of type:* labels.
  • Squash merge only; delete branches post-merge.
  • Share this strategy in repo READMEs and onboarding docs. [NEW]
  • Document exceptions (e.g., legacy branches, vendor integrations) in CONTRIBUTING.md.

9. FAQ & Guardrails

  • Do we need develop? Optional; skip if deployment model supports feature/release branches.
  • Where do we record “type of work”? Project Type field (from branch) and Issue Type on linked issue.
  • How do type:* labels work? Issue Types are the primary classification; type:* labels are automation-managed companions applied by the labeling agent for routing, reporting, and project mapping.
  • Can we add prefixes? Yes—extend CI regex and project mapping together.

[NEW]

  • What if a branch is incorrectly named? CI will block the PR from merging; rename the branch and re-open the PR.
  • How do I handle urgent fixes outside business hours? Use hotfix/, notify the team via Slack/Teams, and ensure all protections are respected.

10. References

11. Appendix: Getting Started

  1. Create or update org-level .github defaults (workflows, labeler, protections).
  2. Sync labels using gh label or .github/labels.yml.
  3. Add branch protection rules to every repo.
  4. Share this policy in repo README and onboarding documentation.
  5. Enforce via CI and maintain with regular review.

12. Advanced Practices & Troubleshooting

  • For monorepos, coordinate releases and branch protection across all workspaces.
  • If CI blocks a merge due to naming, run git branch -m <old> <new> locally, then push and re-open PR.
  • Use GitHub Branch Protection API for automation.
  • Escalate persistent issues to Engineering leads via issue or Slack.

13. Onboarding & Training

  • New contributors must review this document and complete onboarding modules.
  • Include branch naming and merge training in onboarding sessions.
  • Add cheat sheets and workflow diagrams to internal wiki.