Code review on GitHub

Why this matters

You will be reviewed constantly and asked to review more often than you expect: documentation, interface wording, error messages, release notes. The mechanics take five minutes to learn. The manner is what decides whether people want you on their pull requests.

The mechanics

Reviews are written on the Files changed tab. Hovering a line shows a comment icon; clicking it opens a comment box on that line.

Prefer Start a review for anything longer than a one-line fix: the author gets one notification instead of twelve, and you can revise a comment before anyone sees it.

The Viewed checkbox is underrated on a large pull request. It collapses each file as you finish it and remembers, so an interrupted review can be resumed rather than restarted, and new commits un-tick the files they touch.

The three verdicts

Request changes is the one to use deliberately. It is right for a factual error or a broken step; it is heavy-handed for a preference, because the author cannot merge until you come back and re-review. For preferences, use Comment and say "non-blocking".

If a review requesting changes is holding up work and its author is unavailable, an Admin can dismiss it with a reason, which is recorded on the pull request.

Suggestions

For anything that is "this word should be that word", write a suggested change rather than a sentence describing it. In the comment box, the suggestion button inserts a fenced block pre-filled with the selected lines:

```suggestion
Yes. Trailguide is free for everyone, including commercial use.
```

The author sees a diff and a Commit suggestion button, or can collect several with Add suggestion to batch and commit them together. This is the most useful review skill for documentation work: unambiguous, one click, and the resulting commit credits you as co-author.

Writing a comment that helps

Three habits make a reviewer easy to work with. Mark what is optional with "nit:" or "non-blocking:", so the author knows what must change. Say one good thing, briefly; it changes how the rest reads. Review promptly or say when you can, because a pull request waiting two days is a person blocked for two days.

Being reviewed

• Read the whole review before replying. Half the comments often answer each other.
• Answer every thread, even with "done" or "kept as is, because…". Silence reads as ignoring.
• Push fixes as new commits rather than amending, so the reviewer can see what changed since they looked. The squash on merge tidies it anyway.
• Re-request review from the sidebar once you have addressed everything; that is what returns it to their queue.
• Resolve conversation on threads you have acted on, if the repository requires resolution before merging.

Reviewing as a non-developer

You are qualified for more than you think, and not for some of it, and saying which is which is the professional move.

For the rest, say so: "I reviewed the documentation only; the Python needs someone else." That is a useful review, and it stops your approval being read as more than it was.

How to do it

$ git fetch
$ git switch docs/12-windows-install-steps

Common mistakes

• Twelve separate comments instead of one batched review.
• "Request changes" for a preference, which blocks the merge until you return.
• "Reword this" without saying how. Use a suggestion.
• Approving without saying what you looked at, which implies more than you checked.
• Leaving threads unanswered as the author.
• Force-pushing mid-review, which detaches the comments from the commits they referred to.
• Reviewing only the diff when the change is a set of instructions. Follow them.