A PR with 47 files, a "fix bug" description, opened on Friday afternoon. The reviewer approves out of exhaustion, and the defect reaches production with two signatures on it. That scenario shows up in every team that reviews code, and almost all of it is avoidable.

How you write the pull request shapes the whole team's cycle time. A well-made PR takes the reviewer straight to the point that needs judgment and answers the testing question before it is asked.

What blocks a review

  • Scope too large. A PR touching 15 files across 3 contexts goes past 20 minutes of review, and the reviewer chooses between studying all of it or approving on the surface. Surface approval becomes approval without reading. The Google Testing Blog post In Praise of Small Pull Requests measures the effect of PR size on review and defect detection.
  • Generic description. "Refactor" forces the reviewer to read the whole diff to reconstruct your intent.
  • Formatting mixed with logic. Reindentation and import reordering in the same PR hide the line that changes behavior.
  • No new test. The reviewer opens the diff looking for the test that proves the change and does not find it. The reviewer asks, and the cycle extends one more day.

Anatomy of a PR that clears review fast

Title with a type

Conventional Commits handles it: feat(auth): rotate jwt-autenticacao-completa" class="post-internal-link">refresh token on login tells type, scope, and change without opening the PR page.

Description in three blocks

## What
Automatic refresh token rotation on login.
The previous token is invalidated in the same request.

## Why
Fixes CVE-2024-XXXX: a long-lived token without rotation
suffers session fixation after logout.

## How to review
- Start with the middleware in `auth/refresh.ts`
- The invalidation logic is in `token-store.ts:47`
- The integration test for the flow is in `auth.test.ts`

A single responsibility per PR

The rule I apply: the PR has to fit in 20 minutes of review by someone who knows the domain. Past that, the diff reads incomplete, and you lose the second opinion you requested the review for. The GitHub documentation on pull requests describes the feature-branch and review flow this pattern uses.

Formatting in its own PR

Reformatted the file? Send the formatting PR on its own, with the tool explained in the description. The logic PR stays readable, and git blame points at the behavior change instead of the formatter.

Evidence of the result

Changed UI? Add the before and after screenshot. Changed performance? Add the measured number. Changed visible behavior? Attach a short GIF of the flow. The reviewer validates the change without checking out the branch.

Self-review before the request

Open the diff as if it belonged to someone else. Look for leftover console.log statements, a TODO that stayed behind, dead comments, unused imports. Two minutes here save the back-and-forth cycle that stretches a PR over days.

Checklist before you request review

  • Title with a Conventional Commits type.
  • Description with what, why, and where to start reading.
  • A single responsibility per PR.
  • Formatting outside the logic change.
  • A test for the case you added or changed.
  • Screenshot, number, or GIF for a visible change.
  • No leftover console.log, debugger, or TODO.
  • The diff read once by you, with a reviewer's eyes.

Every item you skip becomes a question in review, and a question becomes another review cycle. The GitHub feature on protected branches covers the required-approval requirement before merge. The rest of the checklist belongs to whoever opens the PR.