Optimizing pull request for developer happiness

We as developers create a lot of pull requests from building new features to fixing bugs and typos.

When we create pull requests it is important to optimize for easy review by other developers and even by yourself at a later point in time. The goal of PR is to keep it simple, clutter-free and allow others to review without any cognitive overhead.

1. Provide clear context

• It is better not to make assumptions in the pull request. Since the person reviewing it might not understand all the discussion that happened elsewhere outside the pull request
• If there are links to slack discussions / other documentations do mention them too
• Explaining why the code change is needed and what it does helps
• Don't use big words or any jargons if it is not needed
• If you do something new in the codebase explain it
• Follow some pull request template so that structure of the PR description is always the same and it is easy to find things

2. Write code spec document if possible

• When you are about to work on a big feature that would affect everything. To avoid any surprise you could write a simple spec document of change you propose to do and get it reviewed by other devs in your team
• This would allow you to avoid later disagreements and complete rewrite after the code is written
• This might not always be needed but will help for very big features

3. Keep PR size small

• It is better to have few changes in PR as possible
• If the feature is big rather than a shipping feature in a single PR it might be possible to break the feature into smaller features and ship it incrementally (ship it in parts at least to staging). That way the feature is easy to review and spot bugs. And you if would find issues with the feature and don't have to re-work the feature completely when everything is done
• If you find some other issue while writing the code create a different PR to fix the issue

4. Add Video / screenshots

• If you have visual changes add video or screenshots of the changes in the PR description
• If it is a bug fix provide screenshots of before and after the change. So that they don't have to jump to issues to see the bug

5. Host the changes

• Host the PR and provide a link for the reviewer to checkout
• You could use automated deployments to create preview URL for PR in frontend codebase using Vercel or Netlify

6. Highlight critical changes

• If there is any critical change you could highlight them by adding a Github comment explaining why you did it and providing more context
• You could also add a small video of walkthrough through the code changes if needed
• If you think there is something to look out for write down that too

7. Don't squash the commits once the review has begun

• Squashing commits during the review will make it harder to track changes for the reviewers

8. Automate repeated checks

• Using tools like prettier, Eslint to automate basic checks will help
• If there is an issue specific to the repo that comes up multiple times in different PR's automate it if possible either using custom Eslint rule or using some other tool so that the reviewer can be sure that issue handled and don't have to think about it

9. Don't get angry over a PR

• If the reviewer suggests some change and you disagree with it. You could disagree in a respectful way explaining your case. It is not worth getting angry over a PR. Since it is just the code change the reviewer disagrees.
• If you learned something new from the code review give a shoutout to the reviewer :)

Photo by Tim Mossholder on Unsplash