Source Control & Branching¶
Status: 🟢 Active | Owner: Engineering Enablement | Last Reviewed: 2025-Q4
Introduction¶
Version control discipline is the foundation of everything else in the delivery pipeline. Clean commits enable meaningful changelogs and efficient bisection. Short-lived branches enable fast feedback and avoid integration pain. Code review is the organisation's primary mechanism for knowledge sharing and early defect detection. These standards govern all three.
The organisation uses GitHub as the single platform for all source control. Every production-relevant codebase — services, libraries, infrastructure-as-code, golden path templates, and this standards portal itself — lives in GitHub under the acme-internal organisation.
Non-Negotiable Rules¶
| Rule | Rationale |
|---|---|
main is always deployable | CI must be green before merge; broken main is the highest-priority fix |
| Feature branches ≤ 2 days | Longer branches cause integration pain and delay feedback |
| Signed commits required | Verifiable authorship for audit and compliance |
No direct push to main | All changes via PR; branch protection enforced in GitHub |
No merge commits on main | Squash and Merge keeps history clean and each commit deployable |
| Delete branches after merge | Auto-configured; stale branches cause confusion |
| Secrets never committed | Gitleaks pre-commit hook blocks; Vault provides runtime secrets |
Separation of Duties in Source Control¶
| Activity | Performed By | Verified By |
|---|---|---|
| Writing code and committing | Engineer | Automated (lint, format, tests) in CI |
| Code review | Peer engineer(s) | GitHub branch protection (min. 1 approval) |
| Security review | Engineer; Security Engineering for high-risk changes | SAST CI gate; optional security review request |
Merge to main | Author (after approvals); never reviewer-initiated without author consent | GitHub branch protection |
| Emergency hotfix merge | On-call engineer (self-approve) | Post-facto review within 24 hours |
| Repository configuration | Platform Engineering | Change management process |
No engineer reviews and merges their own non-trivial changes. The two-person integrity principle applies to all changes to critical services.
What You Will Find Here¶
| Page | Intent |
|---|---|
| Git Standards & Commit Conventions | Required git configuration, Conventional Commits format, atomic commits, what never to commit |
| Branching Strategies | Trunk-Based Development as the default; feature flags for incomplete work; release branching for regulated products |
| Pull Request Standards | PR size limits, required description sections, merge requirements |
| Code Review Guidelines | Reviewer responsibilities, comment classification, author responsibilities, reviewer behaviour standards |
| Mono-repo vs Multi-repo | Decision framework, approved tooling, hybrid approach |
Last reviewed: 2025-Q4 | Owner: Engineering Enablement