The GitHub pull request review workflow

This guide will walk you through the entire pull request review workflow on GitHub, from creating and reviewing PRs to managing reviewers and filtering PRs by reviewer. We'll also cover how to restrict who can dismiss pull request reviews.

Creating a pull request

To start the review process, you need to create a pull request. Here's how:

1. Create a branch: Create a new branch with your code changes and push it to remote.
2. Start the PR creation flow: Navigate to the repository on GitHub, and you'll see a prompt to create a pull request once you've pushed the new branch. Alternatively, go to the "Pull requests" tab and click on "New pull request".
3. Select your branch: Choose the base branch (e.g., main) and the compare branch (your feature branch).
4. Fill out your PR details: Provide a descriptive title and detailed description of your changes. This helps reviewers understand the context and purpose of the PR.
5. Finish creating the PR: Click on "Create pull request" to complete the process.

Adding reviewers to a pull request

After creating a pull request, it's important to add reviewers who will evaluate your code changes. Here's how to add reviewers in GitHub to a pull request:

1. Navigate to the PR: Go to the "Pull requests" tab in your repository and select the pull request you want to add reviewers to.
2. Add reviewers: On the right sidebar, you will see the "Reviewers" section. Click on the gear icon or the "Reviewers" dropdown, then select the users you want to add as reviewers.
3. Notify reviewers: Once added, GitHub will notify the reviewers of the new PR that requires their attention.

Reviewing a pull request on GitHub

To review a pull request on GitHub, follow these steps:

1. Open the PR: Navigate to the "Pull requests" tab and open the pull request you need to review.
2. Review the code changes: Go through the changes in the "Files changed" tab. Here, you can view diffs and add comments to specific lines of code by clicking the plus icon next to the line number.
3. Choose your review outcome: Once you've reviewed the changes, click the "Review changes" button. You can choose from three options:
   • Comment: Provide feedback without approving or requesting changes.
   • Approve: Approve the changes if the changes look good, and you don't find anything blocking.
   • Request changes: Request changes if you find issues that are blocking and need to be addressed.
4. Submit your review: After selecting an option, add any additional comments in the text box and click "Submit review".

Managing pull request reviews

GitHub provides features to manage and streamline the review process:

Filtering pull requests by reviewer

You can filter pull requests by reviewer to easily see which PRs require your attention or have been assigned to a specific reviewer:

1. Navigate to the repository: Go to the "Pull requests" tab.
2. Filter options: Use the "Reviewers" dropdown on the right side to filter PRs by specific reviewers. This helps in quickly identifying the PRs you need to review or those assigned to other team members.

Restricting who can dismiss pull request reviews

Sometimes, you may want to control who can dismiss pull request reviews to maintain code quality and integrity. GitHub allows repository admins to restrict this capability:

1. Access repository settings: Navigate to the repository and click on "Settings".
2. Branch protections: Under the "Branches" section, click on the "Add rule" button to create or edit branch protection rules.
3. Require pull request reviews: Enable the "Require pull request reviews before merging" option.
4. Restrict dismissal: Check the "Restrict who can dismiss pull request reviews" box. Then, specify the users or teams who are allowed to dismiss reviews.
5. Save changes: Click "Save changes" to apply the new settings.

Best practices for pull request reviews

1. Provide clear and actionable feedback: Be specific about the changes you are requesting or the issues you are pointing out. This helps the author understand and address your concerns efficiently.
2. Be respectful and constructive: Code reviews are a collaborative process. Provide feedback in a respectful and constructive manner to foster a positive and productive development environment.
3. Use GitHub's review tools effectively: Utilize GitHub's inline commenting, review requests, and filtering features to streamline the review process and ensure thorough evaluations.
4. Review in a timely manner: Promptly reviewing pull requests helps maintain development momentum and reduces the risk of merge conflicts.

For further reading on best practices for reviewing pull requests see these empirically supported code review best practices.