09 — Git Workflow

Savoy Signature Hotels — Branch-per-feature + Worktree development workflow

Overview

Every development task — whether a new module, a bug fix, or a refactor — MUST happen on its own isolated git branch inside a dedicated git worktree. Direct commits to main or develop are never allowed for feature work.

main         ← stable / production
  └── develop    ← integration branch (all PRs target this)
        └── feat/m14-room-grid   ← your feature branch (in its own worktree)

Branch Naming Convention

Branch names follow the same prefixes as Conventional Commits:

Type	Pattern	Example
New module	`feat/m{XX}-{kebab-name}`	`feat/m14-room-grid`
Feature	`feat/{kebab-description}`	`feat/booking-bar-integration`
Bug fix	`fix/{kebab-description}`	`fix/hero-slider-mobile-overflow`
Refactor	`refactor/{kebab-description}`	`refactor/mapper-shared-types`
Documentation	`docs/{kebab-description}`	`docs/storybook-guide-update`
Chore / infra	`chore/{kebab-description}`	`chore/upgrade-storybook-10`
Style only	`style/{kebab-description}`	`style/faqs-spacing-fix`

Rules:

Always lowercase kebab-case after the / — no spaces, no uppercase
Module branches always include the number prefix (m{XX})
Keep names short and descriptive (3–5 words max after the prefix)

Step-by-Step Workflow

Step 1 — Ensure `develop` branch exists

git fetch origin
git branch -r | grep develop || git push origin main:refs/heads/develop

If develop doesn’t exist on the remote, create it from main (run once per project).

Step 2 — Create the feature branch

Branch off develop, never off main:

git fetch origin
git checkout -b feat/m14-room-grid origin/develop
git push -u origin feat/m14-room-grid

Step 3 — Create an isolated worktree

Worktrees let you work on the feature branch without touching the main working directory:

# Go back to main working tree
git checkout main

# Create an isolated worktree for the feature branch
git worktree add ../worktrees/m14-room-grid feat/m14-room-grid

# Move into the worktree
cd ../worktrees/m14-room-grid

Worktree naming: ../worktrees/{branch-short-name} (strip the type prefix, keep the identifier).

Step 4 — Develop inside the worktree

All implementation happens inside ../worktrees/{name}/:

Write code, SCSS, stories, tests
Run pnpm install if needed (pnpm links shared packages)
Commit frequently with Conventional Commits:

git add packages/modules/src/m14-room-grid/
git commit -m "feat(m14): add RoomGrid types and mapper"
git commit -m "feat(m14): implement RoomGrid component and SCSS"
git commit -m "test(m14): add RoomGrid mapper and rendering tests"
git commit -m "feat(m14): register RoomGrid in module registry"

Step 5 — Pre-PR checklist

Before opening the PR, verify all quality gates pass from inside the worktree:

pnpm --filter modules test — all unit tests pass
pnpm --filter storybook visual:test — Pixel Perfect visual tests pass
pnpm typecheck — no TypeScript errors
pnpm lint — no lint errors
Max 400 lines changed — split into smaller PRs if larger
Visual baselines committed (__figma_baselines__/ + __visual_snapshots__/)

Step 6 — Open PR to `develop`

gh pr create \
  --base develop \
  --title "feat(m14): Room Grid module" \
  --body "$(cat <<'EOF'
## Summary
- Implements M14 Room Grid module (Phase A + B)
- Storybook stories with 6 variants
- Mapper + rendering tests
- Pixel Perfect visual tests pass

## Test plan
- [ ] Run `pnpm --filter modules test`
- [ ] Run `pnpm --filter storybook visual:test`
- [ ] Verify all 8 themes render correctly
- [ ] Check responsiveness at 375px, 768px, 1024px, 1440px

🤖 Generated with Claude Code
EOF
)"

Always target develop — never main for feature branches.

Step 7 — Clean up after merge

Once the PR is merged:

# From repo root (main working tree)
git worktree remove ../worktrees/m14-room-grid
git fetch origin --prune
git branch -d feat/m14-room-grid

Branch Protection Summary

Branch	Who merges	Source
`develop`	Via PR from feature branches	`feat/`, `fix/`, `refactor/*`, etc.
`main`	Via release PR from `develop`	`develop` only

Quick Reference Card

# ── START FEATURE ──────────────────────────────────────
git fetch origin
git checkout -b feat/m{XX}-name origin/develop
git push -u origin feat/m{XX}-name
git checkout main
git worktree add ../worktrees/m{XX}-name feat/m{XX}-name
cd ../worktrees/m{XX}-name

# ── DEVELOP & COMMIT ───────────────────────────────────
git add <files>
git commit -m "feat(m{XX}): ..."

# ── FINISH FEATURE ─────────────────────────────────────
pnpm --filter modules test
pnpm --filter storybook visual:test
gh pr create --base develop --title "feat(m{XX}): ..."

# ── CLEAN UP AFTER MERGE ───────────────────────────────
git worktree remove ../worktrees/m{XX}-name
git branch -d feat/m{XX}-name