Problem Statement
If you work in a large organization, you might have faced this problem. The backlog of pull requests (PRs) pending review keeps increasing. This can lead to delays in shipping features, fixes, and improvements. This also means that valuable changes are stalled, and contributors may lose momentum or motivation to drive those PRs to completion.
In this blog, we will discuss some of the best practices that can help you reduce the number of pending pull requests, improve the efficiency of reviews, and ensure that changes are consistently delivered with high quality.
Following are some of the best practices that you can implement:
1. PR Ownership
The responsibility for moving a PR forward lies with its author. It’s your code, so you should drive the review process, follow up with reviewers, and feel confident about shipping once it’s approved.
Think of it like owning a pet—you have to feed it, take care of it, and sometimes remind others to help out. No one wants a sad, neglected PR sitting around!
If you are a technical lead or a manager, you should enforce this practice by holding the author accountable for the PR.
2. Review Your Own Pull Request First
Before you even ask someone else to review, take a look at your own PR. Review the code like you’re the reviewer. You’ll catch issues early and avoid back-and-forth on things that could have been fixed right away.
You can use the following tips to make your PR review easier for reviewers:
-
Don’t Assume Reviewers Have Full Context: As the author, you’ve spent significant time on the code, so it feels familiar. Reviewers won’t have the same depth of knowledge.
- Provide a detailed description of the PR: Explain why the change is needed, what’s included, and any potential impact on other parts of the system.
- Include screenshots, videos, or Loom links if your PR affects the UI or functionality.
-
Add Comments: Leave comments in your code, especially if you’ve made decisions that aren’t immediately obvious. If you used a workaround or a non-standard approach, let reviewers know why.
- Example: When ESLint or Rubocop makes linting changes in your pull request, let the reviewer know that this isn’t where you should focus in this pull request.
3. Respect Reviewers’ Time
You can use the following tips to make your PR review easier for reviewers:
- Static Code Analysis: Implement tools that perform static code analysis. These tools catch linting issues and code smells early, allowing reviewers to focus on the core logic rather than surface-level problems.
- Make Testing Easy: Provide pull request review apps so that reviewers can easily test your changes without setting up everything locally.
- Auto-Labeling PRs: Automatically labeling PRs with relevant tags (e.g., bug, feature, refactor, high priority) helps reviewers quickly understand the context and prioritize.
- Code Coverage: Ensure that your PR includes adequate tests. This provides confidence that the changes work and don’t introduce regressions. High code coverage improves the likelihood of a smooth review and approval process.
4. Pull Request Size Matters
- Limit to 20 Files: PRs should ideally have less than 20 files changed. Large PRs require much attention from the reviewer and increases the chance of partial reviews or PRs being postponed.
- Break Down Features:When developing a feature, split the work into smaller, logical PRs. For example, submit separate PRs for database models or configuration changes. Use feature flags to integrate these changes incrementally rather than piling everything into a single, large PR.
5. Code Reviews: Provide Value
-
Constructive Feedback: Reviews should provide actionable, constructive feedback rather than just pointing out what’s wrong. This keeps the process positive and helps the author learn and improve.
- Example: Instead of saying “This is not good”, you can say “This is not good because it would break the XYZ feature. Can you please fix it?“.
-
Be Specific: When suggesting changes, be precise about what needs improvement. This helps the author understand the exact areas that need attention and leads to faster revisions.
- Provide Examples: Share code snippets or examples to illustrate your points. It aligns the author to the exact change that you want.
- Explain Why: Explain why the change is needed. Share the benefits of the change.
- Test Locally: While it’s fair to assume the author has tested the code, you should run the changes locally or in the review app to ensure everything works as expected. Approving untested code can lead to bugs in production.
Closing
By applying some of these practices, you can reduce PR backlog, improve code quality, and create a smoother review process. IMO, it is all about ownership, communication, and making reviews as easy as possible for everyone involved.