Code review workflow
Pull request states from creation through merge or closure.
Every team has a pull request process, but most teams have never drawn it. This template maps the journey from draft creation through reviewer assignment, feedback loops, and final merge: Draft (work in progress), Ready (PR is ready for eyes), Reviewing (assigned to a reviewer), ChangesRequested (feedback received), InProgress (author is updating), Approved (passed all checks), and Merged or Closed.
The key insight is separating Draft from Ready: it marks the boundary where the author thinks their work is ready to consume reviewer time. Once that line is clear, you can measure cycle time and identify whether your team is bottlenecked on review speed or on author rework velocity.
When to use this template
- Engineering process documentation — post this in your contribution guide so every engineer knows what each state means, who owns the next action, and what they should be doing right now with a stalled PR.
- SLA and metrics — measure time-in-review, rework cycles, and merge velocity by tracking state transitions. Comparing these numbers across your team reveals whether you have a review capacity problem or a code quality problem.
- Onboarding new contributors — the state machine replaces a 20-minute walkthrough with a visual contract: "Draft means don't bother reviewers yet, Ready means it's yours to do, Reviewing means you're waiting, ChangesRequested means it's your turn again."
How to adapt it
Extend the state machine to match your organization's review policy:
- Add automatic CI blocking — insert a "CI Running" state between Ready and Reviewing where the PR waits for tests and linting before reviewer assignment.
- Track merge conflicts — add a Conflict state from InProgress if your team blocks merges while main has moved ahead, forcing the author to rebase before the next review round.
- Support multiple review rounds — add transitions from Approved back to Reviewing if your senior architects need to sign off after peer review completes.
The visual editor makes it easy to add states and redirect transitions — your changes regenerate clean Mermaid state diagram syntax, so the result fits straight into your contribution documentation or process wiki.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
stateDiagram-v2
[*] --> Draft
Draft --> Ready: Mark ready for review
Ready --> Reviewing: Reviewer assigned
Reviewing --> ChangesRequested: Issues found
Reviewing --> Approved: All checks pass
ChangesRequested --> InProgress: Author updating
InProgress --> Reviewing: Push changes
Approved --> Merged: Squash and merge
Approved --> Closed: Abandoned
ChangesRequested --> Closed: Rejected
Merged --> [*]
Closed --> [*]
Frequently asked questions
- What is a code review state diagram?
- It maps the lifecycle of a pull request from its creation as a draft through reviewer feedback, requested changes, final approval, and merge. Each state represents a clear handoff: who is responsible now and what action is expected next. It helps teams standardize when a PR is ready for review, what blocking feedback looks like, and when it is safe to merge.
- Why does this diagram split 'Ready' from 'Draft'?
- Because many teams distinguish between PRs that are still in progress (draft) and those that are actually ready for reviewer eyes. Some tools auto-notify reviewers only when a PR moves from draft to ready, preventing noise from mid-commit-message PR noise.
- What happens if a reviewer rejects a PR after approval?
- That's a policy choice. This template shows approval as terminal — once approved, only the author can decide to close (abandon) or proceed to merge. If your team allows re-review after approval, add a transition from Approved back to Reviewing.
- How do I adapt this for my CI/CD gating?
- Add a 'CI Running' state between Ready and Reviewing if you gate review assignment on CI passing. Or add 'Conflict' as a state after InProgress if your team blocks merges while main has moved ahead. The visual editor lets you add states and transitions without syntax — build your exact policy visually.