​
Stacked PR Workflow (Nomey Style)

We use a stacked PR system to build and review epics incrementally — without getting blocked or creating long-lived zombie branches.
You are expected to follow this process. It’s lightweight, fast, and scales well.

​
✅ Core Principles

  • Each PR builds on top of the previous one.
  • Only the top of the stack gets merged.
  • If something goes wrong, delete everything above it and restack.
  • Review happens top-down, fix happens bottom-up.

​
🔁 How It Works

  1. Create a base branch for your epic:
git checkout -b auth/01-base
  1. Do your work, push, open a PR to main.
  2. When you’re ready for the next chunk: 
git checkout -b auth/02-jwt auth/01-base
  • Build the next chunk on top of the previous branch.
  • Push and open a second PR to main.
  1. Keep going:
auth/03-session → based on auth/02-jwt
auth/04-ui → based on auth/03-session
  1. You only merge the top PR (e.g., auth/04-ui) — this pulls in all prior work.

​
🧼 What If Something Goes Wrong?

If a PR in the middle sucks (say, auth/02-jwt):
  • Close and delete all PRs above it (03-session, 04-ui)
  • Fix 02-jwt
  • Recreate the stack on top of the fixed branch
Don’t try to salvage broken stacks. Just rebuild. It’s fast.

​
🧠 Why This Works

  • You don’t get blocked waiting on reviews.
  • You can review PRs in reverse (top-down) without context loss.
  • You only ever merge good, stable code.
  • You avoid stale branches and huge PRs at the end of an epic.
  • Good code isn’t lost just because a later PR has issues.

​
🚫 What Not to Do

  • Don’t merge intermediate PRs.
  • Don’t rebase unless absolutely necessary (e.g. main changes).
  • Don’t let PRs rot for days — keep momentum.
  • Don’t open a PR for every ticket. Stack related work.

​
🛠 Tips

  • Use clear branch prefixes: auth/01-, auth/02-, etc.
  • Keep PRs small and scoped — don’t try to do too much per layer.
  • Use draft PRs if you’re mid-stack and still figuring things out.
  • Squash commits within a PR if it helps, but don’t squash across PRs.

​
Example Stack

main
└── auth/01-base → PR #101
    └── auth/02-jwt → PR #102
        └── auth/03-session → PR #103
            └── auth/04-ui → PR #104 ✅ ← merge this one
You only merge the last one (04-ui).
If something is wrong in 02-jwt, delete 03 and 04, fix 02, and restack.

​
Still Confused?

Ping @peter with a link to your PRs and we’ll clean it up together.