Introducing stacked pull requests to your engineering org can seem like a big change to your code review workflow, but it doesn’t need to be painful. While many code changes will still be small enough for a single, un-stacked PR, sharing a few best practices with your team around reviewing PRs in a stack can help you seamlessly introduce stacking into your engineering workflow and get the full benefits of doing so. With these simple guidelines, you’ll provide relevant, timely feedback to the stack’s author and keep changes flowing smoothly.

Best practices for reviewing stacked PRs

Here’s how we recommend you & your team to review stacked pull requests with Graphite:

1. Review a PR in a stack as though it was an independent change: If the PR doesn’t make sense without a lot of additional context from the stack, request that the author split up the stack differently to make each change more atomic.

2. Review stacked PRs as soon as you’re tagged as a reviewer: Don’t wait for downstack changes to be approved and merged, as this serializes reviews and greatly reduces the time savings of stacking.

3. Start from the bottom: If you’re tagged as a reviewer on multiple PRs in the stack, review from the bottom of the stack (closest to main) upwards.

4. Check for upstack changes as you review: If code in the stacked PR you’re reviewing changes again upstack (indicated by an orange bar on the right in Graphite), click to view the upstack change. You can then navigate back to the PR you were reviewing using the stack visualization (or navigate down the stack with the keyboard shortcut ⌘ + Shift + ↓) and finish your review with the context of the upstack change.

Make your stacked PRs easy to review

Reviewing is only part of the stacking workflow - you should also make sure to follow best practices when creating stacks to make them as easy as possible to understand and review:

1. Separate stacked PRs logically: Each PR should be easy to understand and review independently - see best practices frameworks for splitting up large changes into stacks for ideas on how to do this.

2. Submit PRs as soon as they’re ready to review: Even if you plan to stack additional changes on top, you should submit your changes for review to ensure you get feedback as quickly as possible.

3. If you’re actively working on a PR, mark it as a draft: Open PRs in a stack should be considered ready to review, so if you’re still working on the PR or need to go back and make changes to address review feedback you should mark the PR as a draft until it’s ready to be reviewed again.

4. Choose the best reviewers for each PR in the stack: Choose who is most relevant for each individual change (or set up automations to do this for you) - you most likely don’t want the same set of reviewers to every PR.

5. Use “merge when ready” to put stack merges on autopilot: Unless a change needs manual assistance to land, default to turning on “merge when ready” to ensure your stacked PRs merge quickly once approved.

Set up your org for successful stacking

Lastly, make sure your engineering organization is set up to start stacking successfully with the following best practices:

1. Update your branch protection rules in GitHub: Turn off “dismiss stale approvals” & “require approval of the most recent reviewable push” settings in GitHub to ensure stacks merge smoothly.

2. Assign reviewers automatically with automations: Set up automations in Graphite to automatically assign the most relevant reviewers for each PR based on file types & paths. Automations is a more powerful and granular system than CODEOWNERS for assigning reviewers, built for teams building in large monorepos.

3. Warn authors about large PRs: Set up an automation to comment on PRs larger than 250 lines of code or 25 files changed to encourage authors to break up larger changes into stacks.

By following these simple best practices for reviewers, authors, and your organization, you’ll be set up for success when introducing stacking to your workflow, and ensure that you’re maximizing the time savings stacked PRs can provide in the review cycle.