Skip to main content

Branching model

The git topology that makes per-shop deploys + cross-shop code-sharing work.

Drafted from planning · v0.1

The branches​

main                     ← canonical code; protected branch
shops/swicked            ← Swicked's deployable branch
shops/{slug}             ← one per shop
feat/slice-N-something   ← feature branch off main
fix/issue-description    ← bug-fix branch off main

Flow​

              main
                │
       ┌────────┼──────────────┐
       ▼        ▼              ▼
shops/swicked  shops/mike-s    feat/slice-5-sales
       │        │              │
       ▼        ▼              ▼
   helm-       helm-      (PR back to main)
   swicked     mike-s-bikes

main​

  • Protected branch
  • All PRs target main
  • Tests must pass
  • Bible's npm run build must pass

main is not deployed automatically — it's the source of truth that shop branches rebase onto.

shops/{slug}​

  • One per shop
  • Differs from main only by wrangler.jsonc env block + (rarely) shop-overrides/{slug}/
  • Push to this branch triggers per-shop deploy via CI

To bring a shop up to date with main:

git switch shops/swicked
git rebase main
git push --force-with-lease origin shops/swicked
# CI deploys

Feature branches​

  • Branch off main: git switch -c feat/slice-5-sales main
  • Work, commit, push
  • Open PR targeting main
  • Merge when review + CI green
  • Delete the branch

Bug fix branches​

Same pattern, fix/ prefix. PR description should reference the incident if applicable.

Hotfix flow (urgent shop-specific)​

For "production is broken at one shop right now":

# Branch off the shop's branch (NOT main)
git switch shops/swicked
git switch -c hotfix/swicked-receipt-bug

# Fix
git commit -am "Fix receipt rendering"

# Push directly back to shops/swicked (CI deploys)
git switch shops/swicked
git merge --ff-only hotfix/swicked-receipt-bug
git push origin shops/swicked

# Then cherry-pick to main
git switch main
git cherry-pick <commit-sha>
git push origin main

# Other shop branches will pull this in when they next rebase

Document the hotfix in docs/incidents/.

When to branch vs commit directly​

Solo dev mode: small commits directly to main are fine when you're certain (typo, docs tweak). Anything that touches code or schema should land via a feature branch and PR — even self-reviewed.

Once a team forms: everything via PR.

PR conventions​

PR description should answer:

  • What this changes
  • Why
  • Test plan (what to verify locally)
  • Bible updates (if applicable, link the section)
  • Rollback plan (usually "git revert")

PR template TBD. For now, use the structure above.

See also​