There's a way to measure an engineer's technical maturity that goes beyond the code they write: how they write pull requests. A well-crafted PR is not just code: it's communication, documentation, and respect for the time of the people who will review it.

Bad PRs arrive on Friday afternoon with 47 modified files, a three-word description ("fix bug"), and no context about what changed, why it changed, and what the reviewer should pay attention to. Most people in that situation approve the PR out of fatigue, and that's a real technical risk.

What makes a PR hard to review

Before talking about what works, it's worth understanding what doesn't:

  • Scope too large. A PR that touches 15 files across 3 different contexts is nearly impossible to review deeply. Reviewers don't have enough context to evaluate everything, and end up approving superficially.
  • Absent or generic description. "Refactor" or "Update logic" say nothing. The reviewer has to read the entire diff to understand what was done.
  • Style changes mixed with logic changes. Reformatting and reindentation in the same PR that changes business logic makes it hard to find what matters to review.
  • No testing context. "How do I validate this works?" is the question every reviewer has, and that a good PR answers before it's asked.

The anatomy of a well-made PR

Descriptive title with type

Follow Conventional Commits in the title: feat(auth): add JWT refresh token rotation is much better than "Update auth". The type, scope, and what changes should be visible without opening the PR.

Structured description

An effective PR description answers three questions: What was done? Why was it needed? How should the reviewer approach it?

## What
Adds automatic refresh token rotation on login.
Previous tokens are invalidated in the same request.

## Why
Resolves CVE-2024-XXXX: long-lived tokens without rotation
are vulnerable to session fixation attacks after logout.

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

Focused scope

The practical rule: a PR should be reviewable in under 20 minutes by someone with domain context. If it will take longer, break it into smaller PRs. That's not bureaucracy, it's respect for the review process.

Separate reformatting from logic

If you're going to reformat a file, do it in a separate PR. That way the reviewer of the logic PR can focus on what matters, and the git history stays clean.

Screenshots and evidence

For UI changes, before/after screenshots are mandatory. For performance changes, before/after numbers. For behavior changes, a short video or GIF of the flow.

This is not optional, it's part of the responsibility of whoever opens the PR to prove the change works as expected.

Self-review before opening

A practice that transforms PR quality: review your own PR before assigning a reviewer. Open the diff as if you were someone else. Would you understand what was done? Is there a forgotten debug statement? Any TODO comment that should have been resolved?

Two minutes of self-review prevent review cycles that take days.

The PR checklist that works

  • Does the title follow Conventional Commits?
  • Does the description answer: what, why, how to review?
  • Does the PR touch a single responsibility?
  • Are reformatting changes separate from logic changes?
  • Do tests cover the added/modified cases?
  • Are screenshots/evidence included for visible changes?
  • No forgotten console.log, debugger, or TODO?
  • Did you read your own diff once before opening?

This checklist seems obvious written down. But applying it consistently is what separates engineers who accelerate the team from engineers who create bottlenecks in the review process.