Day 1: How can we make our pull requests easier for reviewers?

First, let’s admit it: reviewing pull requests is really hard. As a reviewer, it’s your responsibility to make sure that the code is correct and of high quality before it gets merged into master. You are expected to do that by looking at a diff and list of files changed. You have to understand what the pull request is trying to achieve, what approach is being taken, what’s going on, and how all these files fit together – enough that you could potentially suggest an improvement. You may have to be on the lookout for typos or style problems. That’s a LOT of stuff a reviewer needs to do, especially in a large pull request!

How can we make our pull requests easier for reviewers?

Today, the challenge is to share one important thing to consider when creating a pull request. You should nominate another one after posting yours.

I’ll start with a simple one,

Make smaller pull requests

Making smaller pull requests is the #1 way to speed up your review time. Because they are so small, it’s easier for the reviewers to understand the context and reason with the logic. It’s easy to make big pull requests. It’s difficult to make small, logical ones that are quick to review, push, and achieve velocity with. But in the meantime, it’s definitely worth time breaking down your issues or pull requests before you commit them in one massive push.

I nominate @Bawantha_Rathnayaka :yum:


Write useful descriptions and titles
Writing a useful description in the “details” section of your pull request can almost be as effective as making a smaller pull request! If I do make a large pull request, I’ll make sure to spend a lot of time making a really helpful description. The most helpful descriptions guide the reviewer through the code as much as possible, highlighting related files and grouping them into concepts or problems that are being solved. This saves the reviewer a lot of time because they don’t have to read every file to try and group them up and identify related concepts. After that, it’s a lot easier to reason about and review your approach. The pull request author is the best person to do this since they made these files in the first place, and have all the details fresh in their minds. Similarly, a useful summary title (instead of just the issue key) makes it clear to the reviewer what’s being solved at a high level, which takes off one extra step for the reviewer. At the end of the day, both of these things give the reviewer more context around the change that’s happening.

I nominate @Yohan :partying_face:


Make it visual

Add Some screenshots for our front-end changes and screenshots make the job for the reviewer much easier. Also If we can add a GIF or small video of our using the feature (potentially in multiple browsers, if that’s important) to add some extra validation for your UI changes, it’s really good and it’s give visual expression to reviewer. Also we can use GIF file for review some API works with postman or related tools and then it’s give visual expression to review and also then it easy for reviewer.

I nominate @BhathiyaTK :upside_down_face:


Avoid re-formatting

Sometimes you may feel the urge to change the formatting of the existing code to fit ‘your’ style. Please abstain. Every byte you change in the source code shows up in the diff views. Some diff viewers have options to ignore changes of white space, but even with this option on, there are limits to what those diff viewers can ignore. Particularly, they can’t ignore if you move code around.

If you really need to address white space issues, move code around within files, change formatting, or do other stylistic changes to the code, do so in an isolated pull request that does only that, and state so in your Pull Request comment.

I nominate @osusara :wink:


Add comments on your pull request

Have you simply re-indented lines in one file? Is a particular file the “main bulk” of your change? Is a file related to, or coupled with, another in the same pull request? Consider leaving a comment inline, at the top of the file, to let the reviewer know. These help the reviewer navigate your pull request.

Even better, it’s possible to create a pull request with no reviewers allowing you to review it yourself and write comments pointing out the interesting bits before anyone else sees the code.

I nominate @anjisvj :grin:


Have on-point commit messages

I don’t expect everyone to have every line of their Git commit messages down to a strict 72-character limit, (although the first 50 characters are useful as a summary), but a good commit message can help improve a code reviewer’s experience. First, they can make Bitbucket’s auto-generated pull requests more useful, especially for smaller pull requests. Good commit messages can also provide a nice bullet-point-like summary of the code changes as well, and it helps reviewers who read the commits in addition to the diff.

I nominate @Gravewalker :grin:


Keep it simple: One Issue - One PR
Avoid stacking up commits regarding different issues on a PR. Break it down into two or more PRs. It is always a good practice to create an issue and go parallel with that.

I nominate @piumal1999

1 Like

Make sure your branch is even with the repo

Before sending the PR, check whether the repo is even with your branch.
Sometimes you may be working on a issue for few days and sending your PR. So there can be updates on the code that have conflicts with your code. And there can be changes which affect your code. Therefore its good to get the latest version of the code to test the code before sending the PR.

I nominate @janithRS


First things first :joy: Write Readable Code

Writing readable code will result in a better pull request because if code is easy to read, it means it’s easy to review as well. Readable code results in shorter review times and reduces the likelihood of the reviewer needing to ask the author questions.

Hmmm seems like there is no one to nominate :unamused:


End of world population :joy:
Thanks all for sharing your knowledge! :heart:

1 Like