GitHub is becoming the one-stop shop for developers looking to work on open-source and private projects. In an effort to improve its foothold within the developer community, the company has recently improved its code review functionality and launched a marketplace for 3rd party developers to integrate with GitHub. This makes it a good time to look at how to make the GitHub experience more amenable to code review.

Making Pull Requests Code Review Friendly

GitHub is built around the ‘Pull Request’ model, which has all the features of a traditional code review tool and more. Here’s an overview of how it works; this will be the basis for the rest of this article:

1. You finish working on a feature branch and you’re ready to bring it back into a long-living branch (generally master or develop depending on your branching strategy).
2. You create a pull request by choosing the branch with your changes and the branch where you’d like to merge those changes.
3. You choose reviewers to approve the code you’ve written.
4. The people you chose will review the changes. It’s possible that they’ll ask to make some changes before getting an approval.
5. Once you’ve got the required approvals, you can merge your changes.

The major difference with a pull request is that it’s much more difficult to bypass the review step than it is with a traditional review. Without approval, you’ll be physically unable to merge your changes. This ensures that the code review is always done and therefore contributes to having higher quality code merged into the long-living branch.

One drawback is that there’s no way to ask for a code review without also requesting to merge the changes into another branch. There are times when you’d like to get early feedback on the approach chosen to solve a problem. Creating a pull request for this is counter-intuitive at best, dangerous at worst — your code is one approval and click away from being merged. In these cases, it’s best to reach out directly to one of your intended reviewers to get some input.

Creating the Pull Request

If your team is doing many reviews, adding context with a short description of the changes makes understanding the code much easier. If applicable, include links to related issues, tickets and design mock-ups.

It’s easy to get inundated with notifications at first because you’re automatically subscribed to repositories that you have push access to. Every comment, every pull request, every addition to a pull request will generate either an email or web-based notification. Save your inbox from flooding by adjusting the Notifications controls in the Settings for your account.

Choosing Reviewers

Even if you’re using GitHub in a business environment, it’s likely that your team will want to use their personal accounts to boost their public track record. Often times, those accounts will have unuseful names like ‘OriginalEllie’, ‘StoneColdJaneAusten’, or ‘Imagin8’. Asking your team members to put their full name in their profile will make finding them to review your change a whole lot easier.

On July 6, GitHub added a feature called code owners as part of the review process. It’s an easy way to specify which developers are likely to be interested in reviewing the code. You specify code owners by a configuration file in the repository. You can also require at least one review by a code owner before merging.

Reviewing Changes

GitHub’s UI does its best to stay out of the way when reviewing a pull request. That said, there are a few features that come in really useful when reviewing lots of code.

Often times a review will involve lots of whitespace changes. These changes add noise  and distract you from the important changes to review. Whether it’s due to an extra space in an assignment statement or fixing a typo in a comment, adding ‘?w=1’ to the URL will hide whitespace changes from the Files Changed tab.

Another great feature on the Files Changed tab is the ability to cherry pick the commits for which you want to see changes. This is useful when a review has resulted in some changes and you only want to see what has changed since the last time you opened the review. To do this, click on the words ‘Changes from all commits’ on the left of the screen. From there, you can shift-click to choose the commits that you’re interested in. The Files view will refresh to only show the files changed in those commits.

At the moment the Files Changed tab shows files one below the other. There’s no tree structure to get a sense of what’s been changed. This layout choice makes following code from one method call to another a challenge. It often involves lots of searching and scrolling to follow a series of invocations from start to finish.

Future of the Pull Request

GitHub recently launched a marketplace for 3rd party developers to integrate their code review tool into GitHub. This is great for GitHub’s users: more options means more competition, and more competition means tool providers will invest in improving their offering.