Reviewing a Pull Request

Pull Requests Reviews 101

Reviewing a pull request is an opportunity to examine another contributor's changes. While reviewing a pull request, you can extrapolate how someone else solved a problem. It's an awesome opportunity to learn more about how the code works and how others solve problems. Reviewing a pull request is a great learning opportunity!

Add assignees for issues and pull requests

Assignees on issues and pull requests let other team members know who is responsible. The assignee oversees the issue or pull request in an accessible and visible way.

⌨️ Activity: Assign yourself to this issue

1. On the right side of the screen, click the assign yourself text under the Assignees section

Commenting on Pull Requests

As a collaborator on a repository, you will get and give pull request reviews before merging code. This is important! It ensures quality code and maintains momentum of changes to your project.

Responsibilities of a reviewer

As a pull request reviewer, your role is to help the pull request author (thats me!) by making sure:

• Code destined for production is of the highest quality
• Intentional shortcuts (technical debt) are commented on and confirmed
• The greater team is aware of potential risks associated with changes

These broad responsibilities can include more specific goals, like:

• Pointing out potential issues in code quality, security, or business logic
• Suggesting other reviewers to the author, when warranted
• Commenting on, approving, or requesting changes on the PR
• Providing suggestions for alternate or better implementation details

Some repositories use a CODEOWNERS file. The CODEOWNERS file assigns responsibility for certain parts of the code to specific individuals or teams. When the CODEOWNERS feature is enabled, only the code owner has the final authority to approve the pull request. Your review may not be a formal approval, but it does show confidence.

Communicate in pull requests

When an approval or request for changes is not yet needed, consider using comments. Comments enable you to inquire about the proposed change early in the review process. You don't need to wait until something is complete to make suggestions.

⌨️ Activity: Comment on my pull request

1. On the pull request, click Files changed
2. Hover over the line of code where you'd like to add a comment, and click the blue comment icon
3. In the comment window, type a question or leave a more general comment
4. When you're done, click Add single comment

Reviewing Pull Requests

You can also approve or request changes on my pull request.

When you get asked to review something, you should acknowledge the request. Acknowledging a review request could take several forms. It could be leaving a comment on the pull request or leaving a review. In some cases, it could be rejecting the review request altogether.

Before you review, some things to consider

Discern the context

Review the title and body of the pull request to understand the intended change. This should help you identify limitations, boundaries, and other important context.

Observing the progress

As a reviewer, there are certain things to look for when identifying how to best provide feedback. In early stages, reviews should focus on the general direction of the changes. Identify if the goal is possible, rather than nitpicking the style, polish, or wording. Pull requests that are closer to merging should receive a robust review. Thorough testing is one of many ways to ensure the changes won't break the project.

Regardless of timing, focus your feedback on the most essential changes. Suggest changes for minor issues within the pull request. When suggesting major changes, open a separate pull request against the author's branch.

⌨️ Activity: Approve a pull request

1. In the pull request, click the Files changed tab
2. Review the changes in the pull request by commenting on specific lines
3. Above the changed code, click Review changes
4. Type a comment summarizing your feedback on the proposed changes
5. Select Approve to approve merging the changes proposed in the pull request
6. Click Submit review

Using request changes on a pull request

Sometimes, the author might identify that something isn't working. They might need a helping hand 👋 to solve the problem. In other instances, it might only work in their environment. When reviewing a pull request, look at and test the code to pinpoint any bugs or unexpected behavior.

Writing a review

Review the diff

Reviewing the diff, the comparison of the proposed code, in the context of the whole project. Could it introduce performance problems, or security vulnerabilities? Try to predict unintended consequences that this change could cause.

Try it out

For most things, actually trying out the proposed change is a good idea. This makes it a lot easier to tell if the actual change matches the intention. You can do this by:

• Cloning the repository, and checking out to the branch compared in the pull request. Run the application in your local development environment.
• Deploying the pull request to a review-lab or staging environment (as appropriate).

When summarizing your review, let the author know if you completed any of these tests.

Empathy and Constructive Feedback

The goal of providing feedback on a pull request is to ensure that the best possible change is being added. Sometimes, a change isn't addressing the problem in the best possible way. It's the reviewer's responsibility to provide meaningful and constructive feedback.

Requesting Changes 101

Before you submit your review, your line comments are pending and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review and its pending comments, scroll down to the end of the page in the Conversation tab. Then click Cancel review.

Leave a review that asks for changes

If you could check out this code for me and tell me what is wrong, that would be fantastic.

⌨️ Activity: Requesting changes

1. On the pull request, click Files changed
2. Hover over the line of code where you'd like to add a comment, and click the blue comment icon
3. In the comment window, type your comment
4. Click Start a review
   • If you have already started a review, you can click Add review comment
5. Above the changed code, click Review changes
6. Type a comment summarizing your feedback on the proposed changes
7. Select Request changes to submit feedback introducing changes necessary before merging
8. Click Submit review

Requesting changes

Although you may want to leave short comments like: 👍, 👎, awesome!, or no; these don't give the author much detail. Provide comments like the following to enable the author of the pull request to respond:

• This looks like it’ll be helpful to our users, but I’m not sure about the flow. I also have some concerns about the efficiency of these queries.
• Although this feature might be useful, do we have any data that identifies that our users need it?

Step 5: Practice reviews

While you were reading this, I made your suggested changes. If you could approve my pull request, that would be awesome!

⌨️ Activity: Give another pull request review

1. In the pull request, scroll down to the bottom and look for your own review status
2. Next to your review, click Approve changes

As you continue working on GitHub, remember that high quality reviews improve your projects. If you are new to a repository, inquire about what review practices they have so you can hit the ground running.