Skip to content

Branching model

Status: Accepted — ADR-0007 (Option A / Epic F + Epic G). Pipeline/guard enforcement may still be landing — see Epic F children.

Companion: Release strategy · Deployment

Task before branch (non-negotiable)

Never create a feature/fix/docs branch without a GitHub Project task.

  1. Create or pick an Issue on Project #1, #4, or #5.
  2. Branch using the issue number:
<type>/TASK-{ISSUE_NUMBER}-{short-slug}
Prefix Use
feature/ New capability or multi-file work
fix/ Bug fix
chore/ Tooling / deps / non-product
docs/ Documentation-only
hotfix/ Emergency production fix

Valid examples

  • feature/TASK-62-git-process-docs
  • fix/TASK-174-pay-balance-url
  • docs/TASK-75-agents-task-branch-rule

Invalid

  • feature/git-docs (no task id)
  • feat/62-something (wrong prefix / missing TASK-)
  • feature/TASK-62 (missing slug)

Regex (CI — Branch name guard):

^(feature|fix|chore|docs|hotfix)/TASK-[0-9]+-[a-z0-9][a-z0-9-]*$

Also allowed for promotion PRs: release/x.y.z.

CI: reusable workflow bz-platform-context/.github/workflows/branch-name-guard-reusable.yml (wired on platform-context, reservation-api-server, admin-web-app).

Exempt: draft PRs; Dependabot / Renovate / github-actions bots; label skip-branch-name-guard (rare escape hatch).

Branch roles (application repos)

Branch Role Who merges / cuts
feature/TASK-* (etc.) Short-lived work Dev; PR into develop
develop Integration / shared DEV truth Team via PR
release/x.y.z Release candidate for PROD Release owner from develop
main Shipped / audit tip PR from release/* after prod validation
hotfix/TASK-* Emergency fix from main Release owner → patch release → main

bz-platform-context PRs typically target main (docs/contracts only).

Where to branch from

Work Cut from PR into
Normal feature / bugfix develop develop
Platform-context docs main main
Release candidate develop create release/x.y.z (no random features)
Promote shipped release release/x.y.z main
Production hotfix main patch release/x.y.z + back-merge develop

Merge strategy

  • Squash-only into develop and main (linear history).
  • Prefer ff-only when updating local integration branches.
  • Never land unreviewed work directly on main or develop.
  • Delete local branch after squash-merge.

In-scope repos

Primary: reservation-api-server, admin-web-app, venuplus-app, customer-web-app / bz-customer-web-v2, bz-platform-context.

See ../../repo-registry.md.