Pull requests and code review

The sixth Git lunch fell on January 11, 2027, after the holiday break. Over the break the team had used GitHub for real, and Grace had a complaint. "I got forty notification emails and I still could not tell which changes were waiting for me," she said. Priya took that as the lesson's starting point. Most of the collaboration on GitHub happens in pull requests, and once people understand how a pull request moves from opened to merged, the notifications start to make sense.

What a pull request is

A pull request, usually shortened to PR, is a proposal to merge the changes on one branch into another branch, together with a page for discussing and reviewing them. The branch with the changes is called the head or compare branch; the branch that will receive them, usually main, is the base branch. The name comes from asking the maintainers to pull your changes in. A pull request is a GitHub feature, not a Git one: Git can merge branches on its own, but it has no place for comments, approvals or automated checks.

Opening a pull request does not merge anything. It creates a conversation around the changes. Everyone with access can read the description, see every changed line, leave comments on particular lines, suggest edits, and approve or ask for changes. Automated checks, such as tests or a spelling check, can run on every update. Only when the people responsible are satisfied is the pull request merged, at which point the base branch gains the changes and the pull request is closed. A pull request can also be closed without merging, which keeps the discussion on record.

Opening a pull request

After Owen pushed his branch fix-ferry-table, GitHub showed a yellow banner on the repository page offering to compare and open a pull request. He could also have used the Pull requests tab, the New pull request button, GitHub Desktop's Create Pull Request button or GitHub Mobile. On the form he chose the base branch (main) and the compare branch (his), and wrote a title and a description.

A good description saves the reviewer time. It says what changed and why, how it was checked, and anything the reviewer should look at closely. If the pull request finishes an issue, the description can say so with a closing keyword such as Closes #31, Fixes #31 or Resolves #31; when the pull request is merged into the default branch, GitHub closes issue 31 automatically. Repositories can provide a pull request template, a Markdown file that pre-fills the description box with headings and a checklist.

## What changed
Updated the Deer Island ferry timetable in chapter 2 to the winter 2027 schedule.

## Why
The operator changed departure times on January 4. Reader email in #31.

## How I checked
Compared every row with the operator's published timetable.

Closes #31

On the form Owen also requested reviewers, assigned himself, added a label and linked the pull request to the guidebook project board. If a pull request is not ready for review yet, it can be opened as a draft pull request, which shows the work to others and can run checks but cannot be merged until it is marked ready for review. Priya encouraged drafts for long pieces of work, such as Owen's chapter 4 rewrite, so that people could see progress and comment early.

The tabs of a pull request

Every pull request page has four main tabs. Conversation holds the description, comments, review summaries, linked issues, the timeline of events and, at the bottom, the merge box with the status of checks and reviews. Commits lists the commits on the branch. Checks shows automated workflows that ran, such as tests from GitHub Actions. Files changed shows the diff of every changed file, side by side or in one column, and is where reviewers do most of their work.

Reviewing a pull request

A review is a structured response to a pull request. On the Files changed tab, a reviewer reads the diff and can click any line to leave a comment on it. For small fixes, a reviewer can write a suggested change: a proposed replacement for the line that the author can accept with one click, which creates a commit. Comments are collected as a pending review, and when the reviewer has finished they submit the review with one of three outcomes.

The author responds by replying to comments, pushing new commits to the same branch, which update the pull request automatically, and marking conversations as resolved. Reviewers can then re-review. Grace liked the suggested changes feature most: she could fix a misplaced comma in a chapter without asking Owen to do it, and the history still recorded who made each change.

What makes a good review

Priya gave the team a short list. Review the change, not the person. Keep pull requests small, because a reviewer can check two hundred lines carefully but will skim two thousand. Start with the description to understand the goal, then read the diff. Ask questions rather than issue orders, and say clearly which comments are required and which are optional. Use suggestions for small wording fixes. Approve when the change is good enough, not when it is perfect. For authors: reply to every comment, explain your reasoning when you disagree, and thank people. For the guidebook, Grace added one rule of her own: any change to distances, times, tide information or warnings needs a source in the description.

Merging and cleaning up

When the requirements are met, someone with write access merges the pull request using one of the three methods from lesson 3: a merge commit, squash and merge, or rebase and merge. Repository settings decide which methods are allowed. Tidewater chose squash and merge for trail-notes, so that each pull request becomes one tidy commit on main with the pull request number in its message. After merging, GitHub offers a button to delete the branch, and repositories can delete merged branches automatically.

Two more features help busy teams. Auto-merge lets the author ask GitHub to merge the pull request automatically as soon as all requirements are met, which saves waiting for the last check. A merge queue, used by larger teams, lines up approved pull requests and tests each one against the latest main before merging, so that two changes that each passed on their own do not break main together.

Mistakes still get through review sometimes. A merged pull request page has a Revert button, which creates a new branch and a new pull request that reverses the merged changes, using git revert behind the scenes. The revert goes through the same review as any other change, and the history records both the original merge and its reversal, so nobody loses track of what happened. In December a wrong closure notice was merged into TrailCheck, and Priya reverted it from her phone in under two minutes.

Protecting main

Pull requests are only a safeguard if people cannot bypass them by pushing straight to main. Branch protection rules and rulesets, set in the repository or organization settings, can require pull requests before merging, require a number of approvals, require code owner review, require checks to pass, block force pushes and prevent the branch from being deleted. Rosa set rules on main in trail-notes: a pull request is required, one approval is required, the editors' code owner review is required for chapters, and the spelling check must pass. MSBA-161 lesson 3 covers rules in detail.

Reviewing away from the desk

Grace spends several days a month at trailheads checking routes, so she does many reviews on GitHub Mobile. The app shows her review requests in its inbox, displays the diff of each changed file, and lets her comment on a line, approve or request changes, and merge an approved pull request when the checks are green. What it does not do well is long reading, so for a full chapter she waits until she is back at a desk. Owen, who prefers to see the files on his own computer, uses GitHub Desktop: it shows the pull requests for the current repository and can check out a pull request's branch with one click, so he can preview a chapter exactly as it will be merged before approving it.

Reviews also happen through other tools. Visual Studio Code, with the GitHub Pull Requests extension, lets developers review and comment without leaving the editor, and the GitHub command-line tool, gh, can list, check out and review pull requests from a terminal. Whatever the tool, the review is stored on GitHub in the same place, so everyone sees the same conversation.

Pull requests and notifications

Back to Grace's forty emails. GitHub sends a notification when you are asked to review, mentioned, assigned, or when something you are participating in or watching changes. The notifications inbox on the website, reached from the bell icon, groups them and lets you filter by reason, such as review requested or mentioned, mark them done, and save some for later. The Pull requests page also has filters, such as Review requests, which lists exactly the pull requests waiting for you. Grace switched her repository watch settings from all activity to participating and mentions, set email for review requests only, and used the Review requests filter each morning. The forty emails dropped to five.