Last time, we looked at how using feature branches makes life easier, and how you would create a feature branch to make a change and push it up to GitHub for review in the form of a pull request.
Now that a Pull Request is live, someone has to review it. Let’s walk through some of the steps involved in making this process go quickly.
In this portion of the walkthrough, we will pretend that I’ve submitted a pull request, and my extremely talented co-worker Yannick will be reviewing it for me. Let’s follow along!
Finding Pull Requests
First, we need to get to the PR. From a project’s main page, we can see that Pull Requests are a menu option.
Click that to see a list of all the open PR’s.
The pull request I’ve submitted is about adding documentation to a project we are working on together. So Yannick will select that PR and give it a look.
Reviewing a PR
As a reviewer, it’s Yannick’s job to check out the PR for any major issues and to comment on smaller issues he finds in the code. I think a goal here is to be thorough, but to balance that with not taking too much of your time.
On a PR’s main page, we can see the PR’s description and any existing comments about the code.
Start here to understand the scope of the request.
Next, check out the commits tab. This view can be useful to get a first pass at the changes made in the PR as it gives you the commit messages associated with each change. Again, another reason to use descriptive messages!
Now we skip to the File Changes tab to start reviewing.
Commenting on Issues
So, the PR isn’t perfect. No biggie—that is expected. The review process makes it easy for a reviewer to spot issues and for the coder to implement changes.
As a reviewer, you can add comments inline to the change preview on GitHub. Simply click on the little ‘+’ next to the line or lines you have issue with.
As the pull request creator, you can comment on those comments to justify or suggest future actions.
Here is an example where Yannick catches a spot where I left in some old code by accident that should be removed.
Nice catch, Yannick! I follow up, indicating it will be dealt with on this branch
The communication about the code and the changes go right inline with the code itself. This is a good feature of doing code reviews on GitHub.
Dealing with Revisions
We have decided that a modification needs to be made to our original pull request. As the submitter, I will make this modification and update the request. The PR process makes this pretty easy too.
Locally, on my feature branch, I simply implement the changes to fix the problem and commit the changes.
Then I push those changes up to the remote branch again. In this case, the branch was called
docs. And again, we are assuming that
origin is set to be the main GitHub repo. So:
git push origin docs
The PR is automatically updated with the latest changes. As Yannick’s comments are on the code affected by this new commit, those comments are hidden by default.
Next up we will look at how to pull down a pull request to your own “local” machine. This will be for times when merely looking at the code on the web just won’t do, such as when you need to run the code to ensure it does what it’s supposed to.
Then, we will finish off this walkthrough series with merging the pull request and dealing with conflicts if they occur.