AzuTear
fc5c13a4fd
Adds AGENTS.md, DESIGN.md, and docs/* covering architecture, conventions, decisions, checklists, branching, release process, and prompts. Updates README and workflow-feedback-plan to reflect the decoupled GroupName nomination model. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
77 lines
2.2 KiB
Markdown
77 lines
2.2 KiB
Markdown
# Branching Strategy
|
|
|
|
This repository uses a simple trunk-based model with short-lived branches and
|
|
`main` as the deploy branch.
|
|
|
|
For delivery workflow, see [workflow.md](workflow.md). For PR expectations, see
|
|
[CONVENTIONS.md](CONVENTIONS.md#git-and-prs).
|
|
|
|
## Default Model
|
|
|
|
```mermaid
|
|
gitGraph
|
|
commit id: "main"
|
|
branch docs-change
|
|
checkout docs-change
|
|
commit id: "work"
|
|
commit id: "validate"
|
|
checkout main
|
|
merge docs-change
|
|
commit id: "deploy"
|
|
```
|
|
|
|
## 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 work. |
|
|
| Documentation | `docs/<short-description>` | Documentation-only changes. |
|
|
| Chore | `chore/<short-description>` | Tooling or maintenance work. |
|
|
| AI-assisted local work | `codex/<short-description>` | Short-lived Codex branch when branch creation is useful. |
|
|
| Hotfix | `hotfix/<short-description>` | Urgent production correction. |
|
|
|
|
## Main Branch
|
|
|
|
`main` should remain deployable.
|
|
|
|
Minimum expectations:
|
|
|
|
- required checks pass;
|
|
- risky migrations and config changes are documented;
|
|
- production-impacting changes include validation evidence;
|
|
- direct pushes are limited to maintainers or automation.
|
|
|
|
## Feature Branches
|
|
|
|
- Keep scope focused.
|
|
- Rebase or merge from `main` according to reviewer preference.
|
|
- Delete branches after merge.
|
|
- Avoid stacking unrelated changes.
|
|
- Do not include generated build output or handoff artifacts.
|
|
|
|
## Commit Messages
|
|
|
|
Use short imperative subjects that describe the outcome.
|
|
|
|
Examples:
|
|
|
|
- `Fix team profile auth recovery`
|
|
- `Refine admin risk workspace`
|
|
- `Document engineering workflow`
|
|
|
|
Use a longer body when context, migration notes, or validation evidence is
|
|
important for future archaeology.
|
|
|
|
## Hotfixes
|
|
|
|
Hotfixes should restore production safely:
|
|
|
|
1. Branch from the deployed commit or current `main`.
|
|
2. Apply the smallest safe fix.
|
|
3. Validate the failing path.
|
|
4. Deploy.
|
|
5. Merge back to `main`.
|
|
6. Add follow-up cleanup or tests when the hotfix intentionally stayed narrow.
|