template/docs/branching.md

Branching Strategy

This document defines the default Git branching strategy.

For delivery workflow, see workflow.md. For pull request expectations, see CONVENTIONS.md.

Default Model

Use a simple trunk-based model unless the project has a clear reason to add long-lived release branches.

gitGraph
    commit id: "main"
    branch feature
    checkout feature
    commit id: "work"
    commit id: "validate"
    checkout main
    merge feature
    commit id: "release"

Branch Types

Type	Pattern	Purpose
Feature	feature/{{short-description}}	New user-facing or system capability.
Bug fix	fix/{{short-description}}	Defect correction.
Refactor	refactor/{{short-description}}	Behavior-preserving structural improvement.
Documentation	docs/{{short-description}}	Documentation-only changes.
Chore	chore/{{short-description}}	Maintenance work with no product behavior change.
Release	release/{{version}}	Optional stabilization branch for release trains.
Hotfix	hotfix/{{short-description}}	Urgent production correction.

Main Branch

The main branch should remain deployable or releasable according to the project's release model.

Minimum expectations:

• Required checks pass.
• Changes are reviewed when the project requires review.
• Risky migrations and config changes are documented.
• Direct pushes are limited to repository maintainers or automation.

Feature Branches

Feature branches should be short lived.

• Keep scope focused.
• Rebase or merge from main according to project policy.
• Delete branches after merge.
• Avoid stacking unrelated changes.

Release Branches

Use release branches only when needed for stabilization, compliance, or release train coordination.

Release branches should receive:

• Critical fixes.
• Release documentation.
• Version updates.
• No unrelated refactors.

Hotfixes

Hotfixes should prioritize production restoration.

Process:

1. Create a hotfix branch from the deployed commit or release branch.
2. Apply the smallest safe fix.
3. Validate the specific failure path.
4. Release.
5. Merge the hotfix back into main.
6. Add follow-up work for broader cleanup if needed.

Commit Messages

Use meaningful commit messages that explain the outcome.

Recommended format:

{{type}}: {{short imperative summary}}

{{optional context, rationale, or validation notes}}

Examples:

• docs: add starter architecture guide
• fix: prevent duplicate invoice submission
• refactor: isolate payment gateway retries

Merge Policy

Choose one policy per project:

Policy	Best When
Squash merge	Small teams want clean history and one commit per PR.
Merge commit	Teams want to preserve branch context.
Rebase merge	Teams want linear history with individual commits.

Record the selected policy in PROJECT.md or this file.