6. Pull Requests & Code Review

📋 Anatomy of a Good Pull Request

• Title: Descriptive, present tense. "Add rate limiting to login endpoint" not "various changes."
• Description: Three sections minimum: What changed, Why it changed (link the issue/ticket), and How to test it.
• Scope: A PR should do one thing. A 2,000-line PR that adds a feature, fixes three bugs, and refactors a module is nearly impossible to review well. Break it up.
• Screenshots: For UI changes, include before/after screenshots. Reviewers should not need to check out your branch and run the app to understand a visual change.
• Checklist: If your team has a PR template (in .github/PULL_REQUEST_TEMPLATE.md), complete every item.

🔍 Giving Good Code Review

Code review is a professional skill. Bad reviews damage team culture. Good reviews catch real problems and improve code quality without creating conflict.

• Distinguish blockers from suggestions: Explicitly mark comments as blocking (must change before merge), non-blocking (suggestion, take or leave), or nitpick (very minor style).
• Ask questions, don't make accusations: "I'm not sure I follow this logic — could you walk me through how this handles the empty array case?" vs "This is wrong."
• Suggest, don't just critique: "What do you think about extracting this into a separate function? It would make the test easier to write."
• Review logic, not style: If your team has a linter configured, let it enforce style automatically. Spending review time on spacing and quotes is waste.

🤝 PR Etiquette for Authors

• Respond to every comment, even just with a 👍 or "done" — it confirms you read the feedback.
• Never force-push to a branch under active review. It rewrites history and invalidates existing review comments.
• If you disagree with a comment, say so respectfully and explain your reasoning. PRs are collaborative — not every review comment must result in a change.
• Merge your own PR only after explicit approval. Never merge under "I assume they'd agree."