cms.fellies.org/BRANCHING.md

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.