vtuber-awards/docs/branching.md

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. For PR expectations, see CONVENTIONS.md.

Default Model

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.