Make small, incremental changes

Overview

As an engineer, you’ve probably been asked to review a pull request that changes thousands of lines. It's impossible to review, and the author probably struggled to write it too. Large pull requests (PRs) are a pain point for engineering teams everywhere, and they slow down development.

Making small, incremental changes is a best practice that benefits both the author and the reviewers. Smaller changes are easier to understand, test, and deploy, leading to faster feedback cycles and higher quality code.

By making your changes smaller, you can speed up the review process, reduce the risk of bugs, and get your changes to production faster. As a bonus, you're less likely to run into merge conflicts with other engineers' work.

How to do it

• Checked item: Chunk a single ticket logically across multiple pull requests if it's getting large.
• Checked item: Refactor in steps rather than all at once.
• Checked item: Use feature flags to merge incomplete features safely.
• Checked item: Open separate PRs for any unrelated changes you find and want to fix along the way.
• Checked item: Review PRs promptly to keep the feedback loop fast.
• Checked item: Set team norms around PR size.
• Checked item: Set a team norm of reviewing PRs before picking up new work.

Details

Dealing with big pull requests

Despite your best efforts, you may find yourself faced with a large pull request that needs to be reviewed. In these situations, consider the following strategies to make the review process more manageable:

• Consider whether you can break it down after the fact. This can feel like rework, but it's sometimes worth the effort to make the review process smoother, especially if it can be split up just by pulling specific files or commits into separate PRs.
• Do a pair review, with the author walking through the changes with one or more reviewers and answering questions in real time.
• Focus review on the most critical parts of the change, such as core logic or security implications.