On a distributed team, a PR opened at the end of your day can sit for hours before anyone in another time zone sees it. One round of "can you clarify?" costs a full day. These are the habits that keep review fast and useful.
1. Small PRs, always
Small PRs get reviewed faster and more carefully. If a feature is big:
- Split by layer (types → API → UI)
- Use feature flags to merge incomplete work safely
- Stack PRs if your tooling supports it
2. Write the description for someone asleep
The reviewer can't ask you, so answer the questions up front:
## What Adds plot validation errors to the upload screen. ## Why Users couldn't see why uploads failed (ticket #123). ## How - New `validatePlot()` in lib/geo - Error list component with map highlight ## Screenshots / video (before/after) ## How to test 1. Upload fixtures/bad-plots.geojson 2. Expect 3 errors listed ## Notes for reviewer Unsure about the naming in `geo/errors.ts`, open to suggestions.
3. Use comment prefixes
- blocking: must fix before merge
- suggestion: take it or leave it
- question: I don't understand
- nit: trivial, non-blocking
- praise: genuinely good, so say so
This removes ambiguity across cultures and languages.
4. Automate the boring parts
Formatting, lint, types, tests, and bundle size belong in CI. If a human comments on formatting, add a rule instead. (Pre-commit hooks help too. See the Git guide.)
5. Review UI changes visually
- Require screenshots or a short video for UI changes.
- Use preview deployments per PR.
- Check accessibility basics (WCAG 2.2 checklist).
6. Agree on turnaround
Make it explicit, e.g. "first review within one working day." Rotate a reviewer-of-the-day so PRs don't wait for one busy person.
7. Approve with comments
If remaining comments are non-blocking, approve and let the author address them. This saves a whole time-zone round trip.