Review pull requests

Collaborate and work together on GitHub.

Welcome

All great projects start with collaboration. Pull requests are the foundation of teamwork on GitHub — and pull request reviews give you the ability to work together and discuss changes specific to a pull request by commenting, requesting changes, or approving.

  • Who is this for: Developers, new GitHub users, users new to Git, students, managers, teams.
  • What you'll learn: When and how to request a review; how to provide a review of someone else's pull request.
  • What you'll build: We'll be reviewing a pull request for a simple game.
  • Prerequisites: We assume you are familiar with creating branches, commits, and pull requests—you can learn this in our Introduction to GitHub course.
  • How long: This course is five steps long and takes less than 30 minutes to complete.

How to start this course

  1. Right-click Start course and open the link in a new tab.
    start-course
  2. In the new tab, follow the prompts to create a new repository.
    • For owner, choose your personal account or an organization to host the repository.
    • We recommend creating a public repository—private repositories will use Actions minutes. Create a new repository
  3. After your new repository is created, wait about 20 seconds, then refresh the page. Follow the step-by-step instructions in the new repository's README.

Step 1: Open a pull request

Welcome to "Review pull requests"! 👋

Let's get started by opening a pull request.

What is a pull request?: Collaboration happens on a pull request. The pull request shows the changes in your branch to other people. This pull request is going to keep the changes you just made on your branch and propose applying them to the main branch.

⌨️ Activity: Create a pull request

  1. Click on the Pull requests tab in your repository.
  2. Click New pull request.
  3. In the base: dropdown, make sure main is selected.
  4. Select the compare: dropdown, and click update-branch.
  5. Click Create pull request.
  6. Enter a title for your pull request: Update the game over message.
  7. Enter a description for your pull request: Update the game over message so people know how to play again!
  8. Click Create pull request.

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Step 2: Assign yourself

Great job opening that pull request! 👋

What is a pull request review?: Reviewing a pull request is an opportunity to examine another contributor's changes and give them feedback. It's an awesome opportunity to learn more about how the project works and how others solve problems.

The best way to get a review is to ask for one. On GitHub, you can ask someone to review a pull request by assigning them as a reviewer or assignee. If you are not ready for review, consider creating a draft pull request instead.

⌨️ Activity: Assign yourself

  1. Open the pull request you just created.
  2. Under Assignees on the right side of the screen, add yourself.

Because you created the pull request, you can't assign yourself as a reviewer, but feel free to assign a friend as a reviewer instead to see how it works 😄

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Step 3: Leave a review

You assigned yourself! 🎉

Pull request reviews ensure quality and maintain momentum of changes to your project.

When reviewing a pull request:

  1. Review the title and body of the pull request, and possibly any associated issue, to understand the intended change.
  2. Review the diff, the comparison of the proposed code, in the context of the whole project.
  3. For most things, try out the proposed change. Check if the actual change matches the intention. Find the repository's contributing guide to find out how to review the changes.

In your review comments:

  • Identify potential issues, risks, and limitations.
  • Suggest changes and improvements.
  • Share awareness of upcoming changes that the pull request doesn't account for.
  • Ask questions to verify shared understanding.
  • Highlight what the author did well and should keep doing.
  • Prioritize the most important feedback.
  • Be concise and provide meaningful detail.
  • Treat the pull request author with kindness and empathy.

When an approval or request for changes is not yet needed, consider using comments. An approval lets the author know you believe the pull request is safe to merge. Requesting changes lets the author know you believe the pull request is not ready to merge.

⌨️ Activity: Leave a review

  1. On the pull request, click Files changed.
  2. Click Review changes.
  3. Add a comment with your initial thoughts on the pull request.
  4. Select comment. You won't be able to approve or request changes to your own pull request.
  5. Click Submit review.

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Step 4: Suggest changes

Nice work reviewing that pull request ✨

Now that you have explored the different ways you can review a pull request it is time to learn how to use suggest changes.

What is suggest changes?: This feature enables you to recommend a change to a pull request that the author can commit with the push of a button.

⌨️ Activity: Suggest changes

  1. On the pull request, click Files changed.
  2. Find the index.html changes.
  3. Hover your cursor next to the line numbers on the left side of the page.
  4. Click the blue plus icon.
  5. After the comment form appears, click the Add a suggestion button.
    add-a-suggestion-button
  6. Edit the suggestion.
  7. Click Add a single comment.

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Step 5: Apply suggested changes

Nicely done suggesting changes! 🥳

Now let's see how easy it is to apply your suggestion.

⌨️ Activity: Apply suggested changes

  1. Click Commit suggestion.
  2. Type a commit message.
  3. Click Commit changes.

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Step 6: Merge your pull request

Almost there! ❤️

You can now merge your pull request!

⌨️ Activity: Merge your pull request

  1. Click Merge pull request.
  2. Delete the branch update-game (optional).

Next, wait about 20 seconds for actions to run, then refresh this course's README (the one you're following instructions from) and a GitHub Action will automatically close this step and open the next one.

Finish

Congratulations friend, you've completed this course!

celebrate

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.

Here's a recap of all the tasks you've accomplished in your repository:

  • You learned how to assign pull requests for review.
  • You left a review on a pull request.
  • You suggested changes to a pull request.
  • You applied suggested changes to a pull request.

What's next?


Get help: Post in our discussion boardReview the GitHub status page

© 2022 GitHub • Code of ConductMIT License