5 Tips For Reviewing A Pull Request

[mickeygousset]

Authored by: @mickeygousset and @joshjohanning

Introduction

Pull requests (PRs) are a fundamental aspect of collaborative software development, enabling developers to propose, discuss, and integrate changes into a codebase. By creating a pull request, a developer signals that their work is ready for review and potential inclusion in the main project. This process not only ensures that code quality is maintained through peer review but also fosters collaboration and knowledge sharing among team members.

Reviewing pull requests efficiently and effectively is crucial for several reasons. It helps to catch bugs early, ensure code consistency, and maintain high standards across the codebase. Additionally, a smooth review process can significantly speed up the development cycle, enabling teams to ship features faster and with greater confidence.

This post isn't about providing constructive feedback (though that is important), but rather about the process of reviewing a pull request in the GitHub UI, and some of the UI tips and tricks you can use.

These are the top five tips we've find helpful when reviewing pull requests.

1. Using the Rich Diff view
2. Marking a file as viewed
3. Review a specific commit or range of commits
4. Adding a suggestion to a change
5. Switch between unified and split diff views and ignore whitespace differences

1. Displaying a rich diff instead of the source code

The rich diff view in GitHub pull requests provides a more readable and user-friendly way to view changes in files. By default, GitHub shows the changes in the source diff view, which can be difficult to read, especially for non-code files like markdown. The rich diff view shows a preview of how the changes will look once the pull request is merged, making it easier to understand what has changed.

In Figure 1, you can see the source diff view (the default view) of a file in a pull request. To switch to the rich diff view, click on the "rich diff" button at the top of the file (where the arrows are pointing). This will switch the view to the rich diff, as shown in Figure 2.

Figure 1

Figure 2

This rich diff view shows a preview of how the changes will look once the pull request is merged. This can be helpful when reviewing changes to markdown files, for example. You can see the changes in a more readable format, making it easier to understand what text has changed. The rich diff view offers a more intuitive way to see the differences, making it easier to understand the impact of changes.

2. Marking a file as viewed

When reviewing a pull request, you can mark a file as viewed. This is useful when you've reviewed a file and don't need to look at it again. It helps you keep track of what you've reviewed and what you still need to review. When dealing with large pull requests, it's easy to lose track of which files you've already reviewed. Marking files as read helps you keep track of your progress, ensuring that no file is overlooked.

In Figure 3, you can see the option to mark a file as viewed in the pull request view. Click on the "Viewed" button to mark the file as viewed. This will collapse the file in the pull request view, making it easier to see which files you still need to review.

Figure 3

You can also un-mark a file as viewed if you need to review it again. This can be useful if you want to revisit a file or if you accidentally marked a file as viewed. Marking files as viewed can help you stay organized and focused when reviewing pull requests, making the process more efficient and effective.

3. Review a specific commit or range of commits

When reviewing a pull request, you can review a specific commit instead of the entire pull request. This can be useful if you want to focus on a specific change or if you want to see how a specific change affects the code. You can also hold shift + click to select a range of commits.

Reviewing changes incrementally, as they were made, provides better context and understanding of the modifications. It can also help in identifying the specific commit that introduced a bug or issue.

You have two options for finding the specific commit to review. You can either you can use the "Commits" tab to see a list of all the commits in the pull request and select one from there, or you can click on the commit in the pull request view (as shown in Figure 4).

Figure 4

Clicking on a commit will open the commit view, where you can see the changes made in that commit. This can be useful if you want to review a specific change or if you want to see how a specific change affects the code. You can also add comments to the commit to provide feedback or ask questions about the changes.

4. Adding a suggestion to a change

When reviewing a pull request, you can add a suggestion to a specific line or lines of code. This is useful when you want to suggest an improvement. To get started you can click on the line number where you want to add the suggestion. If you want to select multiple lines, you start by clicking on the line number you want to start at and drag down. This will open a comment box where you can type your suggestion.

As you can see in Figure 5, we've added a suggestion to a specific line of code in a pull request. You can do by clicking the "Add a suggestion" button. We have also added a comment to explain the suggestion. Once you've added your suggestion, click "Start a review" to submit it.

Figure 5

Adding suggestions to a pull request improves code quality and fosters collaboration among team members. It provides a way to suggest improvements without directly modifying the code. This can be especially useful when working with junior developers or when reviewing code from contributors who are new to the project.

5. Switch between unified and split diff views and ignore whitespace differences

Depending on your preferences, you can switch between a unified and split diff view by clicking on the gear button. The unified view shows updated and existing content together in a linear view. The split view shows old content on one side and new content on the other side. In figure 6, we can see a visual representation of the two view options.

Figure 6

From the same spot, you can also choose to ignore whitespace changes to get a more accurate view of the substantial changes in a pull request.

Conclusion

Efficiently reviewing pull requests is key to maintaining code quality and ensuring a smooth development workflow. By leveraging GitHub's UI features like marking files as read, reviewing specific commits or range of commits, using code suggestions, utilizing the rich diff view, and switching between different diff options and/or ignoring whitespace differences, reviewers can streamline their process and provide more effective feedback. Implementing these tips not only enhances individual productivity but also contributes to the overall health and agility of the development team. So, the next time you sit down to review a pull request, remember these tips to make the process faster, easier, and more thorough.

[mickeygousset]

If you are interested in the video version of this post, here ya go!

[ivanbonillac]

Great explanation!