Branching Strategy and Conventions

Intent

Define and enforce a simple, traceable branching model with conventional commits, safe merges, and explicit handling for parallel work.

When to Use

• Establishing or revising Git branching strategy.
• Enforcing commit message conventions.
• Coordinating parallel tasks on a shared feature branch.
• Defining merge policies for integration.

Precondition Failure Signal

• Direct commits land on main.
• Merge commits are used for integration.
• Commit messages are non-conventional or verbose.
• Commit message rules are documented but not enforced by hooks or CI.
• Local hooks allow commits on the default branch.
• Feature branches lack traceability to tickets/issues when available.
• Parallel work on a feature branch is done without isolated task branches.

Postcondition Success Signal

• All work lands via feature branches (no direct commits to main).
• Integration uses fast-forward or rebase-only merges (no merge commits).
• Conventional commits are enforced with concise titles and descriptions.
• Local hooks block commits to the default branch.
• Ticket/issue identifiers are included when available.
• Parallel tasks use transient task branches and merge back after verification.

Process

1. Source Review: Inspect existing branching rules, hooks, and CI policies.
2. Policy Definition:
   • GitHub Flow: short-lived feature branches off main.
   • No direct commits to main.
   • Feature branches produce pre-release semantic versions.
   • Merge policy is --ff-only or rebase; no merge commits.
   • Parallel work uses transient task branches per worktree.
3. Implementation:
   • Configure a commit-msg hook and CI to block non-conventional commits.
   • Add a pre-commit hook to block commits on the default branch.
   • Enforce merge policy via branch protection or repo settings.
   • Document branch naming and ticket linkage expectations.
4. Verification: Demonstrate a conventional commit is accepted and a non-conventional commit is blocked.
5. Documentation: Update README or contributor docs with branch and commit rules.
6. Review: Tech Lead, Platform/DevOps, and Release Manager validate policy and traceability expectations.

Example Test / Validation

• A feature branch merge succeeds only with rebase/fast-forward and a conventional commit message.
• A commit attempt on the default branch is blocked by the pre-commit hook.

Common Red Flags / Guardrail Violations

• Pushing commits directly to main for "quick fixes".
• Allowing merge commits for convenience.
• Missing ticket identifiers when issues exist.
• Reusing a single branch for parallel tasks without isolation.
• Relying on documentation alone instead of automated enforcement.
• Bypassing local hooks to commit on the default branch.

Recommended Review Personas

• Tech Lead - validates workflow simplicity and developer fit.
• Platform/DevOps Engineer - validates enforcement via tooling and CI.
• Release Manager / SRE - validates traceability and release impact.

Skill Priority

P2 - Consistency & Governance

Conflict Resolution Rules

• Traceability and quality gates override delivery speed.
• If merge policy conflicts with tooling, fix tooling rather than bypassing policy.

Conceptual Dependencies

• automated-standards-enforcement
• quality-gate-enforcement
• finishing-a-development-branch
• semantic-version-impact

Classification

Governance Core

Notes

Commit conventions:

• Use Conventional Commits with minimal, concise titles and descriptions.
• Include ticket/issue identifiers when available.
• Example: feat(api): add paging support (ABC-123)

Parallel work conventions:

• If multiple tasks are executed in parallel from one feature branch using worktrees, create a transient task branch per task.
• After verification, rebase or fast-forward the task branch back into the source feature branch.