AzuTear
112 lines
2.9 KiB
Markdown
112 lines
2.9 KiB
Markdown
# 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.
|