Git Workflow & Versioning Standard

💡 Copyable AI Prompt Block (AGENTS.md)

<!-- START AGENT-STANDARD: GIT-WORKFLOW -->
                                ## Git Workflow & Versioning
- [ ] **Trunk-Based Development & Short-Lived Branches**: Maintain a continuously deployable `main` branch. Execute all work in short-lived feature branches (`feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `perf/`, `test/`, `ci/`, `build/`, `revert/`) merged within 24–48 hours. Keep feature branches synchronized via `git fetch origin main && git rebase origin/main` (`git merge main` strictly banned). Use `git push origin HEAD --force-with-lease --force-if-includes` when updating remote feature branches post-rebase.
- [ ] **Conventional Commits & PR Title Validation**: Format commit messages and Pull Request titles as `type(scope): description` (scope optional) in lowercase, imperative present mood under 72 characters with no trailing period using approved types (`feat`, `fix`, `chore`, `docs`, `refactor`, `perf`, `test`, `ci`, `build`, `revert`). Require automated CI checks to validate PR titles so squashed commits on `main` preserve commit metadata.
- [ ] **Pull Request & Review Invariants**: Cap PR size under 400 lines of code (excluding auto-generated lockfiles, schemas, or mocks). Enforce mandatory peer review approval (minimum 1 peer/CODEOWNERS approval), passing CI checks, automated secret scanning (`gitleaks`/`trufflehog`), and up-to-date branch protection gates (GitHub Merge Queue recommended) before merging. Require Squash and Merge configured to default to PR title and clean description.
- [ ] **Zero-Downtime Multi-PR Decompositions**: Breaking schema or contract changes MUST NOT be merged in a single PR. Phase 1 (Expand) and Phase 2 (Migrate) PRs MUST be marked backward-compatible (`feat`/`fix`). ONLY Phase 3 (Contract — legacy removal) may include the `!` breaking indicator in the **PR title** (e.g. `feat(api)!: remove legacy schema`) to trigger a MAJOR SemVer bump.
- [ ] **Semantic Versioning & Monorepo Release Automation**: Adhere strictly to SemVer (`vX.Y.Z` or `<package-name>@X.Y.Z` / `<package-name>@vX.Y.Z` for monorepos). Automate release tagging and changelogs on merge to `main` (ANY type with `!` indicator or `BREAKING CHANGE:` footer -> Major, `feat` -> Minor, `fix`/`perf`/`revert` -> Patch; non-breaking `chore`/`docs`/`refactor`/`build`/`ci`/`test` trigger no release). Use pre-release tags (`-rc.N`, `-beta.N`) for staging validation.
- [ ] **Fix-on-Trunk-First Hotfix Procedures**: Emergency hotfixes MUST be committed and verified on `main` first when the issue exists on trunk. Cherry-pick fixes outward to active long-term maintenance release branches (`release/vX.Y`), where automated release pipelines publish patch releases (`vX.Y.(Z+1)`). If an issue is specific to `release/vX.Y` or trunk has diverged significantly, develop against `release/vX.Y` directly and backport to `main`.
<!-- END AGENT-STANDARD: GIT-WORKFLOW -->

---

Detailed Human Guide & Rationale

1. Branching Strategy

• Trunk-Based Development: The main branch is the continuous source of truth and MUST remain in a green, deployable state at all times. Long-lived feature branches, perpetual develop branches, or isolated environment branches are strictly forbidden to eliminate integration bottlenecks and code drift.
• Short-Lived Feature Branches: Developers create short-lived topic branches off main using standardized prefixes: feat/ (new features), fix/ (bug fixes), chore/ (maintenance/deps), docs/ (documentation), refactor/ (code restructuring), perf/ (performance), test/ (tests), ci/ (build/pipeline), build/ (build system), and revert/ (commit reverts). Branches MUST be merged within 24 to 48 hours to minimize merge complexity.
• Trunk Synchronization via Rebase & Safe Force Push: Feature branches MUST regularly synchronize with main by fetching latest trunk commits first: git fetch origin main && git rebase origin/main (or git pull --rebase origin main). Local merge commits (git merge main) inside feature branches are strictly forbidden. Multi-commit feature branches SHOULD run interactive rebases (git rebase -i origin/main) to squash intermediate WIP commits prior to rebasing, reducing conflict friction. When updating remote feature branches post-rebase, developers MUST use git push origin HEAD --force-with-lease --force-if-includes to prevent background fetch race conditions from overwriting concurrent remote pushes.
• Primary Sources & Rationale: Grounded in Paul Hammant & Martin Fowler's Trunk Based Development pattern (trunkbaseddevelopment.com) and Nicole Forsgren et al., Accelerate: The Science of Lean Software and DevOps (2018). Trunk-Based Development with short-lived branches drastically reduces lead time for changes, accelerates feedback loops, and correlates directly with high organizational deployment stability.

2. Conventional Commits & PR Title Validation

• Standardized Structure: Commit messages and Pull Request titles MUST follow the Conventional Commits specification: <type>(<scope>): <description> or <type>: <description> (scope is optional). Approved types are strictly restricted to: feat (minor feature), fix (patch bugfix), chore (maintenance/deps), docs (documentation), refactor (code refactoring), perf (performance improvement), test (adding/updating tests), ci (pipeline updates), build (build system/tooling), and revert (reverting previous commits).
• Imperative Mood & Style: Descriptions MUST be written in lowercase, imperative present-tense mood (e.g., add user authentication rate limit instead of added or adds). Summaries must be under 72 characters and contain no trailing period.
• Pull Request Title Validation: Because GitHub Squash and Merge defaults to using the PR title for the final squashed commit on main, PR titles MUST be validated in CI (e.g. using amannn/action-semantic-pull-request or commitlint). PRs with non-compliant titles CANNOT be merged.
• Zero-Downtime Breaking Change Indicators in PR Titles: Per our architectural standards, breaking structural changes MUST be decomposed into a sequence of backward-compatible PRs following the Expand-Migrate-Contract pattern. Phase 1 (Expand) and Phase 2 (Migrate) PRs MUST be marked as backward-compatible (feat or fix). ONLY Phase 3 (Contract — sunset and removal of legacy schemas or API fields) may trigger a MAJOR bump, and MUST include the ! structural breaking indicator directly in the PR title (e.g., feat(api)!: remove v1 schema) to ensure CI PR title validators and squashed commit parsers capture the breaking change reliably.
• Primary Sources & Rationale: Grounded in Conventional Commits v1.0.0 specification (conventionalcommits.org) and Angular Commit Message Guidelines. Enforcing semantic PR titles ensures automated release tooling (semantic-release, release-it) parses main history accurately without premature major version bumps during multi-phase zero-downtime migrations.

3. Pull Request & Code Review Invariants

• Small PR Footprint (< 400 Lines): Pull requests MUST be kept small, ideally under 400 lines of changed code (excluding auto-generated lockfiles, schemas, or mocks). Large pull requests MUST be decomposed into smaller, incremental, independently deployable PRs.
• Peer Review & Automated Protection Gates: PRs CANNOT be merged into main without at least 1 mandatory peer approval (or CODEOWNERS approval) and all required CI checks passing (linting, static analysis, unit/integration tests, build verification, and automated secret scanning via gitleaks/trufflehog). Branch protection rules on main MUST enforce "Require branches to be up to date before merging" — enabling GitHub Merge Queue is strongly recommended to automate speculative testing and prevent rebase serialization bottlenecks.
• Linear History & Squash Configuration: Repositories MUST enforce "Squash and Merge" as the primary mandatory merge strategy. GitHub repository settings MUST configure Squash and Merge to default to "PR title and description" (ensuring PR template checklists are stripped before merging) so footer metadata (e.g. BREAKING CHANGE:) is preserved cleanly. Non-squashed merge commits (git merge --no-ff) on main are banned to maintain a clean, single-line, bisectable commit history on the trunk.
• Primary Sources & Rationale: Grounded in Google Engineering Practices (How to do a code review / Small CLs) and SmartBear Software research (Cisco Code Review Study). Keeping PRs small, scanning for hardcoded secrets, requiring peer reviews, and gating merges behind passing CI checks increases code review thoroughness, accelerates reviewer turnaround, and guarantees git bisect accuracy during incident debugging.

4. Release Management & Semantic Versioning

• Semantic Versioning Standard (SemVer vX.Y.Z): Version identifiers strictly follow SemVer 2.0.0 (vMAJOR.MINOR.PATCH). ANY commit type containing a ! structural breaking indicator in the title or a BREAKING CHANGE: footer triggers a MAJOR bump. Otherwise, MINOR increments on backward-compatible feature additions (feat), and PATCH increments on bug fixes (fix), performance improvements (perf), and commit reverts (revert). chore, docs, refactor, build, test, and ci commits do NOT trigger automated releases unless accompanied by an explicit breaking indicator.
• Monorepo Package Versioning: Multi-package monorepos MUST use package-scoped release tags (e.g., <package-name>@X.Y.Z or <package-name>@vX.Y.Z conforming to tool defaults like Changesets or Lerna) alongside root project tags to prevent release collisions and maintain independent changelogs uniformly across CI automation.
• Pre-Release Versioning: Pre-release tags (vX.Y.Z-rc.N or vX.Y.Z-beta.N) MUST be used when deploying release candidates to multi-environment staging pipelines for integration and performance testing before cutting final production tags.
• Automated Tagging & Changelogs from Trunk: Release tags and CHANGELOG.md updates MUST be produced automatically upon merging approved commits into main using automated release tools (semantic-release, release-it). Manual creation of release tags or manual version bumps in source code are prohibited.
• Primary Sources & Rationale: Grounded in Semantic Versioning 2.0.0 (semver.org) and Jez Humble & David Farley's Continuous Delivery. Automated release management eliminates manual versioning human error, ensures predictable dependency upgrades, and maintains an accurate audit trail of changes.

5. Hotfix & Emergency Procedures

• Fix-on-Trunk-First Requirement: When a critical production issue occurs, emergency hotfixes MUST be committed and verified on main first (via a fix/hotfix-<issue-id> topic branch off main) whenever the affected code exists on trunk.
• Diverged Streams & Maintenance Branch Execution: If an issue is specific to an active maintenance release stream (release/vX.Y) or if main has diverged significantly with breaking structural changes, the hotfix MUST be developed directly against (or backported to) release/vX.Y. Automated CI/CD release pipelines configured on release/vX.Y then tag and deploy the patch release (vX.Y.(Z+1)) specifically for that release stream. Verified fixes MUST be ported forward to main where applicable to prevent future trunk regressions.
• Fast-Tracked CI Verification: Emergency fixes MUST execute and pass targeted fast-track CI suites (core regression tests, unit tests, secret scans, and security checks) prior to merging. Bypassing automated test verification in CI is strictly prohibited, even during critical outages.
• Primary Sources & Rationale: Grounded in Google Site Reliability Engineering (SRE) Handbook (Incident Response & Remediation) and Trunk-Based Development Hotfix Guidelines. Standardizing hotfix protocols prevents panicked, unverified manual changes from bypassing security and quality gates during high-stress production incidents.