# 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.

## 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.