Branching & pull-request flow

unswayed-backend uses a protected-branch workflow so every change to the integration and release branches is reviewable and traceable.

The branches

• main — stable / release.
• staging — the active integration branch; day-to-day work targets it.

The flow: feature → staging → main

# 1. cut a feature branch from staging
git switch staging && git pull
git switch -c feat/<short-name>      # also: fix/…, chore/…, docs/…, refactor/…

# 2. commit your work on that branch, then publish + open a PR into staging
git push -u origin feat/<short-name>
gh pr create --base staging --fill

# 3. review + merge on GitHub
# 4. release by opening a PR  staging → main
gh pr create --base main --head staging --title "Release" --fill

Enforcement (two layers)

• Local git hooks — active now. .githooks/pre-commit and .githooks/pre-push block direct commits and pushes to main/staging on a developer's machine (merge commits are allowed so integration isn't blocked). They install automatically: the prepare npm script sets core.hooksPath on npm install. Never bypass with --no-verify.
• GitHub branch protection — the server-side, authoritative gate (require a PR, block force-pushes and deletions). It requires GitHub Pro/Team or a public repo; this repo is currently private on the free tier, so it isn't active yet. Enable it (a repository ruleset on main + staging) once the plan allows. Until then the local hooks are the enforcement — and they only cover clones that have run npm install.

Why

Direct commits to integration/release branches bypass review and are easy to get wrong. Routing everything through PRs keeps history clean, enables review, and makes releases deliberate. See ADR-0008 in docs/DECISIONS.md.