Pull Request Etiquette
Rules for sending and reviewing PRs without burning bridges.
For the PR Author
Keep PRs small
A 200-line PR gets reviewed. A 2000-line PR gets skimmed and merged with bugs.
Write a good title
Fix bug should be Fix login crash on empty email field. Be specific.
Describe what and why
Tell the reviewer what changed and why. Context saves hours of back-and-forth.
Link the issue
If there is a ticket or issue, link it. The reviewer shouldn't have to search.
Screenshot UI changes
A picture of the new button is worth 100 words of description.
Mark draft PRs clearly
Use GitHub Draft PR or prefix with [WIP] so nobody wastes time reviewing unfinished code.
For the Reviewer
Review within 24 hours
Blocked PRs kill momentum. If you cannot review, say so.
Focus on logic, not style
If the team has a formatter, let it handle style. Review what matters.
Ask questions, don't demand
Instead of This is wrong, say Have you considered X? It changes the tone completely.
Praise good code
A quick Nice approach on a well-written function makes the author's day.
Be specific about issues
This doesn't work is useless. Line 42 will throw if users is empty is actionable.
Git Branch Naming Convention
| Prefix | Use For |
|---|---|
| feat/ | New feature (e.g. feat/add-login-page) |
| fix/ | Bug fix |
| refactor/ | Code cleanup without changing behavior |
| docs/ | Documentation changes |
| chore/ | Build, config, dependencies |
| test/ | Adding or updating tests |
The Golden Rule
Review code the way you want your code to be reviewed. Kind. Specific. Timely.