113 lines
2.5 KiB
Markdown
113 lines
2.5 KiB
Markdown
# Branching Strategy
|
|
|
|
This repository uses three long-lived branches and short-lived task branches.
|
|
|
|
## Long-Lived Branches
|
|
|
|
- `main`
|
|
- Production release branch
|
|
- Protected
|
|
- `staging`
|
|
- Pre-production verification branch
|
|
- Protected
|
|
- `dev`
|
|
- Integration branch for feature delivery
|
|
- Default merge target for task branches
|
|
|
|
## Promotion Flow
|
|
|
|
1. Task branches merge into `dev`.
|
|
2. `dev` is validated by required checks.
|
|
3. `dev` is promoted to `staging`.
|
|
4. After staging validation, `staging` is promoted to `main`.
|
|
|
|
## Required Checks Before Promotion
|
|
|
|
Minimum gates:
|
|
|
|
- `bun run lint`
|
|
- `bun run typecheck`
|
|
- `bun run test`
|
|
- `bun run test:e2e --list` (or full e2e when infrastructure is available)
|
|
|
|
Recommended for release candidate promotions:
|
|
|
|
- `bun run test:e2e`
|
|
- Build and smoke test Docker images for `web` and `admin`
|
|
|
|
## Short-Lived Branch Types
|
|
|
|
### Delivery Branches
|
|
|
|
Use one dedicated branch per TODO item.
|
|
|
|
Pattern:
|
|
|
|
- `todo/<mvp>-<area>-<slug>`
|
|
|
|
Examples:
|
|
|
|
- `todo/mvp0-rbac-domain-model`
|
|
- `todo/mvp1-media-enrichment-form`
|
|
- `todo/mvp1-public-navigation-render`
|
|
|
|
Rules:
|
|
|
|
- One TODO item per branch.
|
|
- One PR per branch.
|
|
- PR description references exact TODO line text.
|
|
|
|
### Refactor Branches
|
|
|
|
For structural improvements not tied to one TODO task.
|
|
|
|
Pattern:
|
|
|
|
- `refactor/<scope>-<slug>`
|
|
|
|
Examples:
|
|
|
|
- `refactor/db-service-layer`
|
|
- `refactor/admin-routing-structure`
|
|
|
|
### Code Partition Branches
|
|
|
|
For exploratory or larger code partitions outside immediate roadmap tasks.
|
|
|
|
Pattern:
|
|
|
|
- `code/<domain>-<slug>`
|
|
|
|
Examples:
|
|
|
|
- `code/commissions-kanban-poc`
|
|
- `code/media-refinement-module`
|
|
|
|
## Protection Rules (Gitea)
|
|
|
|
Apply in repository settings:
|
|
|
|
- Protect `main` and `staging` from direct push.
|
|
- Require PR merge only.
|
|
- Require status checks to pass.
|
|
- Require at least one review approval.
|
|
- Require branch up-to-date before merge.
|
|
|
|
Optional:
|
|
|
|
- Protect `dev` from direct push if team size/process requires stricter control.
|
|
- Automate protection via `.gitea/scripts/configure-branch-protection.sh`.
|
|
|
|
## Governance Automation
|
|
|
|
- Branch naming check: `.gitea/scripts/check-branch-name.sh`
|
|
- PR TODO reference check: `.gitea/scripts/check-pr-todo-reference.sh`
|
|
- PR template: `.gitea/PULL_REQUEST_TEMPLATE.md`
|
|
|
|
## Commit Signing Notes
|
|
|
|
If commit signing is enabled with GPG, interactive signing prompts can fail in non-interactive contexts.
|
|
|
|
- Local commits: verify GPG agent/session is available.
|
|
- CI commits (if ever needed): use bot keys or skip signed commits for automation.
|