Comments, Suggestions, and Requesting Review

On the Files changed tab, hovering over a line shows a blue plus. Click it and you get a comment box with two buttons, and the difference between them is the most useful thing in this chapter.

Almost always use the second. It is better for the author, who gets a coherent set of feedback rather than a drip. It is also better for you: half the comments you write early in a review turn out to be answered further down, and a pending review lets you quietly delete them instead of posting a correction.

$ gh pr review 483 --comment --body "Looks good, two small things inline"$ gh pr review 483 --approve$ gh pr review 483 --request-changes --body "The export still drops newlines" # Read it locally, which is often faster than the web diff$ gh pr checkout 483$ git diff main...HEAD

Submitting a review makes you pick one of three, and they are not interchangeable — they have mechanical consequences, not just tone.

The other half of the etiquette is how a comment reads. The same technical point can be a collaboration or a verdict, and the difference is mostly grammar.

Two conventions worth adopting because they carry real information. nit: marks a comment as non-blocking taste, so the author knows they may ignore it. And praising something specific is not politeness — it tells the author which decisions to repeat, which is the half of review that never gets written down.

Instead of describing an edit, write it. A fenced block tagged suggestion in a line comment renders as a proposed diff with a button.

```suggestion  if (!res.ok) throw new Error(`loadUser ${id}: ${res.status}`);```

 12   export async function loadUser(id) { 13 +   const res = await fetch(`/api/users/${id}`); 14 +   return res.json(); 15   }

  if (!res.ok) throw new Error(`loadUser ${id}: ${res.status}`);

Press the button and it becomes a real commit on the branch, authored by the pull request author with you recorded as co-author. Checks re-run. The thread becomes resolvable.

1. 1
   Multi-line suggestions work

   Click the line number and drag to select a range before commenting, and the suggestion replaces the whole range.

2. 2
   Batch them

   "Add suggestion to batch" collects several and commits them all as one commit, rather than one commit per typo.

3. 3
   The indentation is literal

   Whatever whitespace you type is what lands in the file. A suggestion that drops two spaces of indentation breaks the code.

Every comment thread on the diff has a Resolve conversation button, which collapses it and marks it handled. It is the mechanism a long review uses to stay readable — twenty threads collapse to the three still open.

It is also a claim, and the etiquette around who presses it is a genuine source of friction.

Threads on a specific line have a second behaviour worth knowing: outdated. Push a commit that changes the line a comment was anchored to and GitHub hides the thread as outdated. The comment is not gone and not resolved — it is collapsed, and it is very easy for a real objection to disappear this way without anybody deciding it was answered.

A pull request nobody was asked to review is a pull request nobody reviews. Requesting a review puts it in a named person's queue — their Review requested filter, which is what most people actually work from.

$ gh pr create --reviewer alice,bob$ gh pr edit 483 --add-reviewer carol$ gh pr list --search "review-requested:@me"     # your actual queue

You can request a team as well as a person, and GitHub will optionally assign a subset by round robin or by load, so the request lands on somebody specific rather than on a group everybody assumes somebody else will handle.

The automatic version is CODEOWNERS — a file mapping path patterns to people or teams. Anyone opening a pull request that touches those paths gets those reviewers requested for them, without having to know who owns what.

# Later rules win, so put the general ones first. *                       @org/maintainers/src/auth/              @org/security/src/billing/           @alice @org/payments*.sql                   @org/data/.github/workflows/     @org/platform

Combined with branch protection's "Require review from Code Owners", this becomes enforcement: a change to the auth directory cannot merge without somebody from the security team, no matter who approved it. That is how a large repository stays safe without a human router in the middle.