# Branching Strategy

This document defines the default Git branching strategy.

For delivery workflow, see [workflow.md](workflow.md).
For pull request expectations, see [CONVENTIONS.md](CONVENTIONS.md#pull-requests).

## Default Model

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

```mermaid
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:

```text
{{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](PROJECT.md) or this file.