Chapter 5: Pull requests and review

What this chapter covers

Somebody has asked you to review their change, or you want to get your own change merged. On the website that means a long page of code with comments wedged between the lines, and a merge box that speaks in colours and icons.

In this chapter you find the pull requests that need you, read one as an outline you can walk, read its changes line by line, comment on a line or a range, suggest a change, and send your review. Then you find out whether it can merge, and why not, and merge it, one or several at a time.

By the end you will know how to review a pull request from start to finish without the website, and how to get one merged safely.

Reading works signed out. Everything that writes needs a signed-in account. Merging, re-running and the other changes also need your account’s Workbench level to allow them: Organize or Full. Chapter 13 explains the levels.

In QUILL Lite, which works as a guest, you can read every part of a review. The commands that write say they need a signed-in account.

Finding the pull requests that need you

Pull requests live in three places in the GitHub Workbench’s tree:

View > Quick Filters narrows a list of pull requests without typing: Review Requested from Me, Reviewed by Me, Drafts, Has Conflicts and Checks Failing are there, with the others. Each is checked while it is on, and they combine. Chapter 13 covers filtering in full.

Opening a pull request

Select a pull request and press Enter. That is Review…, the first row of its context menu, and it opens the review window described below. A pull request link pasted into File > Open GitHub Address… (Ctrl+L) goes straight to it, and so does a pull request in your notifications.

File Differences… (Ctrl+Shift+D, on the Item menu) skips the outline and opens the changed files on their own. More on that below.

The one-sentence summary

The first thing you hear when the review opens is the whole pull request in one sentence:

“Review loaded for pull request #42. Approved, 2 checks failing, 1 open thread, 3 commits behind main.”

The sentence is built from these, in this order, leaving out what does not apply:

A merged or closed pull request just says “Merged.” or “Closed without merging.” The same sentence is the first line of the window, Pull request in one sentence, so you can read it again. Copy Review Summary (Alt+S) copies the fuller summary.

The review window

In Tab order:

The buttons that write are unavailable when you are signed out or the pull request is closed, and Reply is available only with a thread selected.

The outline

The tree is a real tree: Up and Down move between the rows you can see, Right opens a branch and Left closes it. Tab reads the selected row’s details, and Shift+Tab comes back.

Enter on a row does the natural thing: on a file it opens the file’s diff; on a thread it moves you into its details to read every comment and reply; on a check it opens the check on GitHub; on anything else it opens or closes the branch.

Reading or expanding never changes anything. Selecting a thread does not resolve it or mark it read.

Moving between threads

Neither of these tells GitHub anything. “Visited” lives only in this window.

Files you have viewed

GitHub remembers, for you alone, which of a pull request’s files you have viewed, so a long review can be done in sittings. Signed in, the review window reads that after the review loads, and each row under Changed files ends with its state: “src/status.py, viewed”, “src/status.py, not viewed”, or “src/status.py, changed since you viewed it” when someone pushed to it after you looked. The status line says how many you have viewed, such as “3 of 12 files viewed.”

Shift+F10 on a file has:

Changed since my last review

When someone pushes more commits after you have reviewed, you do not want to read every file again. Check Changed since my last review (Alt+L). QUILL finds the commit you last reviewed and keeps only the files that have changed since then. The tree’s first branch is renamed Files changed since your review on and the date, and you hear how many:

If the branch has been force-pushed and the commit you reviewed is gone from GitHub, QUILL says so plainly and shows every file. Uncheck the box to see every file again.

The diff

Enter on a file in the outline, Open File Differences on a file’s or thread’s context menu, or File Differences… (Ctrl+Shift+D) on a pull request in the Workbench, opens the diff window, PR #42 diff: and the title.

Opened from a thread, the diff goes straight to that thread’s lines and says “Review comment at” the file and line. If the line is no longer in the patch, it says so and suggests the thread may be outdated.

Open Diff in Default App saves the diff as a .diff file and opens it in whatever program your computer uses for those, and tells you where the file is.

As you arrow through the patch lines, an added line and a removed line each have a short sound of their own, so you can hear the shape of a change before the words arrive. They are the sounds Arrived on an added line of a diff and Arrived on a removed line of a diff in the Sound Scheme window, where either can be previewed, changed or switched off, and they follow your sound setting like every other QUILL sound. Unchanged lines and headings are silent.

Escape closes the diff and takes you back to where you opened it.

Commenting on a line or a range

In Patch lines:, arrow to a line and press Enter, or press Comment on This Line… (Alt+L). To comment on several lines, hold Shift and arrow to select them, then press Enter or Comment on Lines… (Alt+S). With one line or none selected, Comment on Lines asks you to type the range instead, such as 12-15, 12 to 15 or just 12.

GitHub takes a comment only on lines the patch shows, and a range only inside one block of changes. QUILL checks before it sends and tells you which rule the lines broke, such as “Line 30 is not in this file’s changes, so GitHub will not take a comment on it.”

The comment window is titled with where the comment goes, such as “Comment on line 12 of src/status.py”. It has:

Most of the time you want Add to Review. GitHub then sends your comments together, with your verdict, as one review, and people are notified once instead of once per comment.

Suggesting a change

Check Suggest a change and QUILL puts the lines you chose into the comment as a suggestion block, ready for you to edit into what they should say. On GitHub, the author can accept a suggestion with one button. Uncheck it to take the block out again. A suggestion replaces lines of the new file, so it works on added and unchanged lines, not removed ones.

Pending comments and sending your review

Comments added to your review are kept on this computer, for your account, until you send them. You hear “Added to your review:” and where, and how many are waiting. They show in the outline under Pending line comments, not sent yet, each with its place and the start of its text.

On a pending comment, Enter or Edit Pending Comment… changes it, and Delete Pending Comment… removes it after asking. It was never sent, so it cannot be got back.

Compose Review

When you are ready, press Compose Review… (Alt+C). The window Review Pull Request #42 says how many line comments go with this review, and has:

The review message saves as you type, so closing the window loses nothing. Submit Review is the only thing that sends. Request changes asks once more before it goes. You hear “Review submitted on pull request #42.” and how many line comments GitHub took with it.

GitHub never lets you approve your own pull request. If you keep a second account for that, see Approving with another of your accounts below.

When the pull request moves under you

Comments are written against one version of the code. If new commits arrive before you send, the lines you commented on may have moved. QUILL will not send a review whose comments were written on an older version: it says how many were, and asks you to delete or rewrite them under Pending line comments first. If the version changes while the Compose window is open, nothing is sent, and QUILL tells you to reopen the draft against the current diff.

Replying and resolving

On a thread in the outline:

The thread’s context menu has these, plus React to a Comment…, Copy Conversation, Copy Thread Link, Open File Differences and Open Thread on GitHub.

Ctrl+R replies only here, in the review window. In the Workbench it refreshes the list.

Reviews already sent

Reviews…, on a pull request’s context menu in the Workbench (under More), lists every review the pull request has had, with who sent it and its verdict. Choose one, then what to do with it: read its comments, and change or delete one of them; change its summary; dismiss it, when GitHub lets you; or, for a review still pending, submit it or delete it. Anything that changes a review asks first.

Re-request Review… asks people who have already reviewed to look again, after you have pushed changes. Give their GitHub names, separated by commas.

Getting a pull request merged

Reviewers, draft and ready

Asking Copilot for a review

Request Copilot Review, on the pull request’s context menu in the review window (Shift+F10 on the outline), asks Copilot code review to review the pull request. It has no button or access key. You hear “Copilot review requested on pull request #4.” only when GitHub lists Copilot among the reviewers. GitHub sometimes accepts the request and leaves Copilot off the list, which is how it answers an account or a repository without Copilot code review; QUILL says that plainly rather than telling you a request went in when it did not. Copilot’s review arrives as review comments, like anyone else’s, and the outline shows them after a refresh.

In the Workbench, Ask Copilot to Review, on a pull request’s context menu under More, does the same from the list. The same menu has Agent Merge, Turn On Agent Merge and Turn Off Agent Merge…, which let Copilot’s cloud agent merge the pull request once its checks and reviews allow. These need a Copilot plan with the cloud agent; Chapter 12 has the rest of Copilot’s commands.

Merging

Merging is in the Workbench, not the review window, because it is the one thing here that changes the base branch for everyone. Select the pull request and press Ctrl+Shift+Enter, or choose Merge… from its context menu or the Item menu.

QUILL first asks GitHub whether the pull request can merge. If it cannot, you hear why, the same answer as Why Can’t I Merge? below, and nothing else happens. If it can, QUILL asks how to merge: Squash and merge, Merge commit, or Rebase, offering only the ways the repository allows. Then it asks you to type the pull request’s number to confirm, not just press Yes, and says what will happen: that it merges into the base branch, as of the commit QUILL checked, for example “as of commit 3f9a2c1”, and that this changes the branch for everyone and cannot be undone from QUILL. You hear “Merged #42” and the start of the new commit.

That commit is the one that merges. If somebody pushes to the pull request between the check and your typing the number, GitHub refuses, nothing is merged, and QUILL says so: “Somebody pushed to #42 after commit 3f9a2c1 was checked, so nothing was merged.” Check again and you are merging what you have actually read.

When the base branch merges only through a merge queue, Merge… does not try to go around it: you hear that the pull request can join the queue, and Add to or Remove from Merge Queue… puts it there.

A merge cannot be taken back with Ctrl+Z. To undo one, use Revert Pull Request…, below.

Merging several at once

To merge more than one pull request, select them in the list (hold Shift or Ctrl with the arrow keys), then choose Merge Selected… from the context menu or the Item menu. It needs at least two open pull requests selected; anything else in the selection is left out.

  1. QUILL asks once how they should merge: Squash and merge, Merge commit, or Rebase. Where a repository does not allow that way, QUILL uses one it does, and the preview says which.
  2. It asks GitHub about each pull request on its own, with the same question as Why Can’t I Merge?. One that cannot merge does not hold up the others.
  3. The preview lists every pull request: “#42: will merge into main by squash and merge, commit 3f9a2c1.”, “#43: will join the merge queue for main” when its branch requires a queue, or “#44: will not merge.” and the reasons. The first line sums it up, such as “Of 3 pull requests: merge 2; 1 will not.” Press Enter to go on, or Escape to change nothing, and then type how many will go in.
  4. QUILL merges them one at a time, about a second apart. Just before each one it asks GitHub again, because merging one can make the next conflict or put it behind its base. A pull request that can no longer merge, or that has new commits since the preview, is left alone, and says why: you agreed to merge the commit you were shown, not a later one. A failure stops nothing else.

At the end you hear one sentence with the counts, such as “Merged 2 of 3 pull requests, 1 not merged.”, and the results list has a line for each pull request. Copy Results copies them, and Retry Failed (F8) starts again with only the ones that failed, preview and all.

Why Can’t I Merge?

Why Can’t I Merge? on a pull request’s context menu in the Workbench answers the question GitHub’s merge box answers with colours and icons. You hear either that it can merge, “#42 can merge into main, as of commit 3f9a2c1.”, or each reason it cannot, each with what to do:

Each blocking rule is said by name, so you know whom to ask or what to fix. QUILL reads the rules that apply to the base branch (its rulesets, and its branch protection when you can read it) and says:

What QUILL could not read, such as branch protection without admin access, is said at the end, so a missing permission never sounds like “no rule”. GitHub’s answer is the one that counts: naming the rules never turns “can merge” into “cannot”. Merge Selected… names the rules the same way in its preview, for each pull request that will not merge.

It also says when auto-merge is on, and its place when the pull request is in the merge queue. The answer is always for one commit, which it names, so you know a push after you asked may change it.

Watch Readiness

Watch Readiness, on an open pull request’s context menu in the Workbench, adds a watch (under Watches, Ctrl+7) that tells you once when the pull request becomes able to merge, and once when it stops, naming the rule that blocks it then. It is checked with your other watches, on the same interval, and said the same way. The first check only learns where it stands, and while GitHub is still working out whether it can merge, nothing is said. You can also add one from Watches with Add Watch…, choosing “A pull request becomes able to merge, or stops being able to”. The watch is kept on this computer only; nothing is changed on GitHub.

Auto-merge and the merge queue

On a pull request’s row in the Workbench, Auto-Merge… turns auto-merge on, after telling you what it would be waiting for and asking how to merge, or offers to turn it off when it is on. A pull request that can merge now has nothing to wait for, and QUILL says so rather than switching it on. Add to or Remove from Merge Queue… adds the pull request to its branch’s queue, naming the commit, or offers to take it out when it is in, saying its place. The repository’s Merge Queue place lists the whole queue in order.

In the review window, Auto-Merge and Queue… (Alt+A) opens a menu:

Each asks first, and reports what GitHub confirmed. When GitHub refuses for a reason QUILL knows, it says what to do about it, for example that auto-merge is turned off for the repository and an administrator can turn it on in the repository’s settings, or that GitHub can merge the pull request now, so there is nothing for auto-merge to wait for.

Merge policy

Check Merge Policy, in the review window, reads the rules on the base branch: required reviews, required checks, code owners and the merge queue. It adds them to the review summary, and from then on the readiness and the combined check status count only the checks that are required (“3 of 4 required checks pass”). The rules are read for the current version of the pull request; refresh the review after new commits to check again. GitHub always has the last word, and QUILL says so.

A check that needs another run

On a check in the outline, the context menu has Re-request Check…, which asks GitHub to run that check again. Some checks are older-style commit statuses rather than check runs, and those cannot be re-run from outside; QUILL says so. Chapter 6 covers checks and workflow runs in full.

Approving with another of your accounts

GitHub never lets the author approve their own pull request. If you keep two accounts in QUILL, say a personal one and one for the project, Account > Roles and Access > Act As Another Account… sends one action as the other account. Select the pull request first. QUILL lists your other signed-in accounts, then the actions that fit: Approve this pull request, Comment on it, or Close or reopen it. It checks whose token it really is before sending, names the account in the question, and names it again in the result: “Approved pull request #42 in owner/name as jeff-project.” The other account’s own Workbench level applies, so a Read Only account sends nothing.

Compare Accounts…, on the same submenu, shows two of your accounts side by side on this repository: each one’s role, as GitHub answered that account. Chapter 13 has both in full.

The whole patch, a revert, and conflicts

Three commands on a pull request’s row in the GitHub Workbench do what the web’s Files tab, its Revert button and its conflict editor do.

Open Patch in Editor

Open Patch in Editor opens the pull request’s whole change as one document: every changed file, one after another, as a unified diff, the same text the website’s .diff link gives and the text git apply reads. Each file starts with a line beginning diff --git, so the editor’s Find moves from file to file, and each change starts with a line beginning @@, which names the lines it touches. A removed line starts with a minus sign and an added line with a plus sign.

A file GitHub sends no text change for, such as an image or a very large file, is not left out silently: it has a line of its own starting with #, which names the file and says so. When the patch opens you hear how many files it has and how many of them have no text, for example “Opened the patch of #42. The patch has 12 files. 1 of them has no text change GitHub can send, binary or too large, and each is named on a line starting with #.”

The patch is saved as <repository>-pr-<number>.diff in the folder where the Workbench keeps the documents it opens, so Save As keeps a copy anywhere you like.

Revert Pull Request

On a merged pull request, Revert Pull Request… opens a new pull request that undoes it, as the Revert button on the website does. QUILL asks for the new pull request’s title, which starts as Revert " and the old title, and then asks whether to open it as a draft. Yes opens a draft, which nobody can merge until it is marked ready; No opens it ready for review. Nothing is undone until the revert is itself merged, so this is a proposal, not a change to the branch.

You hear “Opened pull request #57, which reverts #42.” A pull request that is not merged has nothing to revert; the command is greyed, and its help says why. You need write access to the repository.

Resolve Conflicts in a Worktree

When a pull request cannot merge because it conflicts with its base branch, Resolve Conflicts in a Worktree… gets the conflicts onto your own computer without touching the folder you are working in:

  1. QUILL asks which local checkout of the repository to use, if the document you have open is not in one, and finds the remote that is that repository on GitHub.
  2. It asks first, naming the remote and both branches. This is the one step that uses the network, and it is your own Git that does it, with your own sign-in, as git fetch from a terminal would.
  3. It makes a new folder beside your checkout, a Git worktree, on a new branch called pr-<number>-conflicts made from the pull request’s branch, and merges the base branch into it there. Nothing is committed.
  4. You hear how many files conflict and their names, and the editor’s Resolve Conflicts walks each one, the same window as QUILL’s Tools > Git and GitHub > Local Git > Resolve Conflicts…: each conflict in turn, with your version and theirs read out, and a choice for each.

When the files are resolved, commit in that folder and push the branch to the pull request’s branch; QUILL says the exact command, for example git push origin pr-42-conflicts:fix-parser. The new folder stays until you remove it with Tools > Git and GitHub > Local Git > Worktrees….

A pull request from a fork is the exception: its branch lives in the fork, not in the repository, so QUILL says so and leaves it to a checkout of the fork, or to its author. If the base merges with no conflicts, QUILL says that instead, and the merge is left staged, not committed.

This one is QUILL’s alone. In QUILL Lite, which has no Local Git, the row is greyed and says why.

Dependabot’s pull requests

A pull request Dependabot opened, to update a package, has Dependabot Commands… on its context menu. It lists the commands Dependabot answers in a comment, such as rebase, recreate, merge, or ignore this version, each with what it does. Choosing one posts it as a comment, after asking, and Dependabot does the rest.

A few more commands on a pull request’s row:

Writing a new pull request

In a repository’s Pull Requests, press Ctrl+N. To start from a branch, select it in Branches, press Ctrl+Shift+N and choose Pull Request. The New Pull Request window has Merge into, Merge from, Title, Description and a Create as a draft check box. The title and description start from the commits you are proposing, a branch that already has an open pull request is taken to that one instead of making a second, and Cancel keeps your text for the session. Chapter 12 walks through it.

On an issue, Start Pull Request for This Issue… makes a branch linked to the issue and a draft pull request that closes it, in one step. Chapter 4 has it.

A walk-through: reviewing and merging the practice pull request

The practice repository has a branch, fix-greeting, with a pull request waiting for you. Make it first with Help > Practice on GitHub… (Ctrl+Alt+P) if you have not. Nothing here matters if it goes wrong.

  1. In the Workbench, press Ctrl+L, type quill-practice and press Enter. You arrive on the repository’s own place in the tree.
  2. Press Ctrl+Shift+2 for its Pull Requests, then F6 to the list. You hear the pull request that fixes the greeting.
  3. Press Enter. The review window opens, and you hear “Review loaded for pull request” and the one sentence.
  4. Arrow down to Changed files, press Right Arrow, and press Enter on the file. The diff opens.
  5. Press Alt+P for the patch lines and Alt+H to check Changed Lines Only. Arrow down: an added line and a removed line each have their own sound. F8 jumps to the next change.
  6. Press Escape to close the diff, and Escape again to close the review.
  7. Back on the pull request in the Workbench, press Shift+F10 and choose Why Can’t I Merge?. You hear that it can merge into main, as of a commit it names. The practice run fails on purpose, but it is not a required check, so it does not stop the merge.
  8. Press Ctrl+Shift+Enter. Choose Squash and merge, type the pull request’s number, and press Enter. You hear “Merged” and the new commit.

You made the pull request yourself, so GitHub would not have let you approve it. On someone else’s, Compose Review (Alt+C) in step 6 is where you send Approve.

Learn it with a guided lesson

Help > Tutorials (Ctrl+F2) has Review and merge a pull request, on the practice repository: list the pull requests, read the change, ask whether it can merge, and merge it. Each step says what to press and what you should hear. Try a command without sending it shows Dry Run, which lets you try Merge… and see what it would send without sending it.