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