Guide to Reviewing Pull Requests on GitHub

You don't need to write code to review a pull request well. Designers catch broken layouts and wrong copy, product managers catch changes that don't match what was agreed, and both notice when a change does more than its description claims. GitHub's review tools are built for exactly this kind of feedback, and a fresh pair of eyes from outside engineering often notices what the author stopped seeing.

Most of a review happens in the Files changed tab, where every edited line appears in red and green. You can comment on a specific line, propose replacement text the author can accept with one click, and mark files as viewed to keep track of your progress. Images get their own comparison views. Comments can be gathered into a single review, so the author gets one notification instead of a stream of separate pings. A review then ends with one of three decisions: a comment, an approval, or a request for changes.

A good review is specific and kind. Pointing to the exact line, explaining why something matters, and suggesting a fix turns feedback into progress rather than a debate. Vague comments like this looks off slow everyone down, while clear ones leave the author knowing exactly what to do next.

The Files changed tab

The Files changed tab shows the diff reviewers use to understand a pull request ^[1]. A file tree on the left lists every changed file, and each file's changes appear with removed lines in red and added lines in green.

Its header shows how many files changed. Starting there, and scanning the file names before any lines, gives a sense of scale and spots surprises early, like a settings file in a pull request that was only meant to change page copy.

Long files can be collapsed, and a filter narrows the list by file type, which helps when a pull request touches design assets and code at once.

Split and unified diff views

GitHub can show a diff in two layouts. The unified view lists removed and added lines one under the other, in a single column. The split view puts the old version on the left and the new one on the right ^[2].

The choice is personal. Split views make edited lines easy to compare on a wide screen, while unified views suit narrow screens and long lines. The gear icon on the Files changed tab switches between them, and it can also hide changes that only affect spaces.

Hiding whitespace is especially useful for AI-generated changes, which sometimes reformat whole files. With spacing changes hidden, the real edits stand out.

Commenting on specific lines

A comment can be attached to a single line of a diff. Hovering over the line and selecting the blue comment icon opens a box right below it, and selecting a range of line numbers attaches the comment to several lines at once ^[3].

Line comments keep feedback precise. Instead of the header text looks off, a comment on the exact line can say what's wrong and why, and the author sees it right where the change is. Each comment becomes a thread the author can reply to and resolve.

When the line changes in a later commit, the old comment is marked as outdated, so the conversation stays attached to the version it was about.

Suggested changes

A suggested change proposes exact replacement text for one or more lines. The reviewer selects the suggestion icon in a line comment and edits the text inside the suggestion block ^[4].

The author can apply it with Commit suggestion, which commits the change straight from the pull request, or gather several with Add suggestion to batch and commit them together. Applying needs write access, and everyone whose suggestion is included becomes a co-author of the commit.

Suggestions are ideal for copy and small style fixes. A designer can correct a heading or a button label in seconds, without opening an editor or describing the change in words.

Pro Tip! Batching suggestions turns a review full of small fixes into one tidy commit instead of a dozen.

Starting a review vs. adding single comments

Comments on a pull request can be sent one by one or gathered into a review. Selecting Comment posts a single comment right away. Selecting Start a review saves it as pending, visible only to the reviewer, and later comments join the same review ^[5].

A review is sent all at once, with a summary and a decision, so the author gets one notification instead of a stream of pings. It also lets the reviewer read the whole change before committing to feedback, and drop comments that turn out to be wrong.

Single comments still suit quick questions. For anything longer than a remark, a review keeps the conversation calmer and easier to follow.

Comment, approve, or request changes

A review ends with Review changes and one of three decisions ^[6]:

• Comment leaves general feedback without approving or blocking
• Approve signals that the changes are ready to merge
• Request changes marks feedback that must be addressed before merging

Whether a request for changes actually blocks the merge depends on the repository's rules. Without a rule that requires reviews, it's informational only ^[7]. Authors can't approve their own pull requests either way.

The decision should match the feedback. Approving alongside a long list of concerns sends a mixed message, while requesting changes over a typo can stall work for a day.

Marking files as viewed

Long pull requests are easier to review in passes. Selecting Viewed in a file's header collapses the file and counts it as done, and a counter shows how many files are left ^[8].

If a file changes again after it was marked, GitHub unmarks it, so new commits never slip past unseen. That makes Viewed safe to rely on across several sittings.

Combined with the file tree, it lets a reviewer split a big pull request into chunks and take a break without losing their place.

Reviewing image changes

When a pull request changes an image, GitHub offers three ways to compare the old and new versions ^[9]. 2-up, the default, shows them side by side. Swipe reveals one over the other with a slider. Onion skin fades between them, which helps when elements move by small, hard-to-notice amounts.

Markdown and other documents get a rich view too: Display the rich diff shows the formatted result instead of the source. Comments can only be added in the source view, though.

For designers, these views make GitHub a workable visual review tool. A shifted icon or a slightly changed color is far easier to spot with a swipe than with two images open in separate tabs.

Writing specific, kind review comments

Helpful review comments are specific about what and why. The heading wraps on mobile because it's 48px. Could it drop to 32px on small screens? tells the author exactly what to look at and offers a way forward. This looks off leaves them guessing.

Tone matters as much as content. Phrasing feedback as a question or a suggestion, and commenting on the change rather than the person, keeps reviews collaborative. Small preferences can be marked as optional, so the author knows what's essential.

Praise belongs in reviews too. Pointing out a clever solution or a careful detail tells the author what to keep doing, and it makes critical feedback easier to hear.