Why pull requests matter

A pull request is not a formality you fill in before merging. It is a handoff document: you are asking a teammate to spend their attention verifying that your change is correct, safe, and worth carrying in the codebase for years.

Professional PRs reduce review time, prevent production incidents, and build trust. Sloppy PRs — huge diffs, missing context, failing CI — force reviewers to reverse-engineer your intent. That slows everyone down and erodes confidence in the team.

The goal is simple: make the reviewer's job easy.

Start before you open the PR

Good PRs are mostly written before you click "Create pull request."

Keep the diff small and focused

One PR should answer one question:

• "Add password reset flow"
• "Fix race condition in cart checkout"
• "Extract billing module from monolith"

If your PR title needs "and" more than once, split it. Reviewers can approve a 200-line diff in minutes. A 2,000-line diff gets skimmed — or postponed indefinitely.

Rule of thumb: if you cannot describe the change in one sentence, it is probably too big.

Make CI green before requesting review

Do not open a PR with failing tests or lint errors and tag someone with "will fix later." That signals the PR is not ready for their time. Run the same checks locally that CI will run. Fix failures first, then request review.

Link the issue (when one exists)

If work started from a tracked issue, reference it in the PR description (Fixes #142, Closes #87). That closes the loop automatically on merge and gives reviewers the original requirements without a scavenger hunt.

The PR title

The title is what reviewers see in notifications, Slack, and their review queue. Make it scannable.

Write it like a commit subject line:

• Present tense, imperative mood
• Specific about what changed
• No ticket-only titles like "PROJ-4821"

Weak	Strong
Updates	Add rate limiting to public API endpoints
Fix bug	Return 422 when checkout receives negative quantity
WIP auth stuff	Support refresh token rotation in auth middleware
PR for review please	Migrate session store from files to Redis

If your team uses Conventional Commits, carry the same prefix into the PR title: feat(auth): support refresh token rotation.

The PR description — use a template

Reviewers should not have to guess what you changed or how to verify it. A short, consistent template saves everyone time.

## Summary
One or two sentences: what this PR does and why now.

## Changes
- Bullet list of the main edits (not a file listing — the diff shows files)
- Call out anything non-obvious: new env vars, migrations, feature flags

## Test plan
- [ ] Unit tests pass locally (`npm test`)
- [ ] Manually tested checkout with expired card → shows retry UI
- [ ] Verified migration runs on empty DB

## Screenshots / recordings
(Required for UI changes — before/after or a short screen recording)

## Risk / rollout notes
(Optional: feature flag name, backfill job, rollback steps)

Summary: explain the why

The summary is not "I changed files in src/auth." It is the reason someone should care:

Users were logged out every hour because access tokens expired without refresh. This PR adds silent refresh so sessions survive token rotation without forcing re-login.

That one paragraph orients the reviewer before they read a single line of code.

Test plan: prove you checked your work

A test plan is a checklist of what you already verified. It is not a wish list for QA.

Be concrete:

• Commands you ran
• Edge cases you tried
• Environments you tested against (local, staging)

For bug fixes, include steps to reproduce before and confirm fixed after.

Reviewers trust PRs with honest test plans. They distrust PRs that say "tested locally" with no detail.

Screenshots and recordings for UI changes

If pixels moved, show pixels. A before/after screenshot or a 15-second screen recording eliminates dozens of "what should this look like?" comments.

For backend-only changes, skip screenshots — but make the test plan thorough instead.

What reviewers need from you

Respond to feedback promptly

When someone leaves a comment, reply or push a fix. Leaving threads open for days blocks the PR and the reviewer mentally. If you disagree, say so respectfully with reasoning — that is valuable review culture.

Do not force-push without warning mid-review

If a reviewer is halfway through reading your diff and you force-push a rewritten history, their comments may attach to the wrong lines. Either wait until review is done, or leave a note: "Rebased onto main — diff unchanged except conflict resolution."

Mark conversations resolved only when addressed

Click "Resolve conversation" after you fix the issue or explain why you will not. Do not resolve threads to make the PR look clean while ignoring feedback.

Request the right reviewers

Tag people who own the code you touched, not everyone on the team. Two focused reviewers beat five drive-by approvals.

Review etiquette as an author

Professional PR authors treat review as collaboration, not judgment.

• Do not take feedback personally. Comments target the code, not you.
• Prefer suggestions over arguments. If a reviewer asks for a rename and it costs five minutes, just do it unless there is a real technical reason not to.
• Split follow-up work when appropriate. If a reviewer finds a pre-existing bug outside your PR scope, open a separate issue instead of ballooning the current diff.
• Say thank you. Review is unpaid labor. Acknowledging it matters.

Common anti-patterns

Anti-pattern	Why it hurts	Better approach
"Big bang" PR mixing refactor + feature + formatting	Impossible to review safely	Three PRs, merged in order
Empty description: "see code"	Reviewer has no context	Fill the template
Draft PR open for weeks	Queue noise	Convert to draft or close until ready
@everyone please review	Alert fatigue	Tag 1–2 owners
Fixing unrelated lint in every file you touch	Hides the real change	Separate chore PR or scoped fix
Arguing in comments for 40 messages	Blocks merge	Hop on a 10-minute call, then summarize decision in the PR

Draft PRs vs. ready for review

Use Draft when you want early feedback on direction but know CI or tests are not done yet. Label it clearly: "Looking for architecture feedback — tests coming tomorrow."

Convert to Ready for review only when you would happily merge it if you were the only person on the team. That is the bar.

After merge

Professional work does not end at merge:

• Delete the branch (most hosts offer a button)
• Watch deploy/monitoring if you shipped something risky
• Update docs or runbooks if behavior changed for operators

Your PR description often becomes the best record of why a change happened. Write it for future-you reading git blame in six months.

Summary

Professional pull requests are small, focused, and review-ready. They have clear titles, honest summaries, concrete test plans, and visual proof when UI changes. They respect reviewer time, respond to feedback quickly, and leave a trustworthy record in the project history.

The best PR is one where the reviewer thinks: "I know exactly what this does, I trust it was tested, and I can approve this in one pass."