Pull-Request Developer Expectations

Timely, thoughtful code reviews keep our velocity high and our quality bar even higher. The guidelines below sit alongside our Git workflow and spell out what we expect—both when submitting and reviewing pull requests (PRs). They are meant to be simple defaults; use good judgement and communicate when exceptions are needed.

1. Submitting Pull Requests

✅ Do this	💬 Why it matters
Keep PRs focused and right-sized. A PR should deliver a cohesive, “whole” piece of work but remain small enough to review in one sitting.	Smaller diffs are faster to review and merge—which keeps trunk healthy and reduces merge conflicts.
Include before/after screenshots when the PR is UI changes only.	Visual diffs give reviewers instant context and reduce back-and-forth.
Write a clear title and description for large PRs that have multiple commits. Summarise why you made the change, link to tickets, and list test steps if relevant.	Shared context makes for higher-quality reviews.
Tag 2–4 reviewers who have touched the code recently using Reviewers (not Owners).	Spreads knowledge and avoids bottlenecks.
Own the merge. The PR creator merges once approvals & CI are green.	You’re closest to the change and can resolve last-minute issues quickest.
Flag urgency. If you need a quicker review than the 24-hour norm, drop reviewers a Slack DM or channel mention.	Async ≠ silent—ask for help when timelines are tight.
Nudge after 2 days. If no review has landed, politely remind tagged reviewers or add fresh ones.	We value momentum; lingering PRs slow everyone.

2. Reviewing Pull Requests

✅ Do this	💬 Why it matters
Target a 24-hour turnaround (1 business day). Block out calendar time for reviews each day.	Reliability builds trust and keeps work flowing.
Prioritize improvement over perfection.	Confirm the feature works; deeper efficiencies or refactors can ship in a follow-on PR.
Choose the right depth. Small/low-risk PR → review in the Git diff. Large/high-risk PR → pull it locally, run tests, click through the UI.	Match effort to impact.
Ask for a walkthrough when a change set is complex.	Live context beats guessing.
Be constructive and specific. Suggest concrete improvements; celebrate good patterns.	Empowers teammates and speeds fixes.
Approve only when you’d ship it yourself. No half-hearted ✅.	Users feel the consequences of our merges.

3. Shared Principles

PRs should be resolved—merged or closed—promptly. Stale branches drift and waste effort.
Use Draft PRs early to surface work-in-progress and gather feedback before polish.
Prefer incremental or stacked PRs for large features instead of one giant diff.
Communicate. A quick Slack message can unblock days of waiting.

Let’s keep our codebase healthy and our feedback loops short. 🙌