Written by Table of contents
- Define “done” up front
- Use a repeatable review checklist
- Validate evidence, not assumptions
- Handle revision rounds efficiently
- Acceptance
- Example decision record
- Keep payment aligned with review
Define “done” up front
In the issue description, include:
- Expected behavior and edge cases
- How to test (manual steps and/or automated tests)
- Any UX requirements (screenshots, copy, responsiveness)
- Non-functional constraints (performance, security, accessibility) when applicable
- Rollout or migration notes when changes affect existing users
Use a repeatable review checklist
- Scope: matches what was agreed
- Quality: readable code, consistent patterns
- Safety: no obvious security or data handling issues
- Tests: added/updated where appropriate
- Docs: updated if behavior changed
Validate evidence, not assumptions
- Reproduce key flows locally or in the target environment.
- Confirm screenshots/videos represent current code, not outdated revisions.
- Check that test instructions in the PR are runnable by another reviewer.
- Verify linked issues and PR descriptions are aligned with delivered behavior.
Handle revision rounds efficiently
- Group feedback by priority (blocking vs non-blocking).
- Reference exact files/lines or failing checks.
- Confirm when each blocking item is resolved.
- Re-run critical validation steps after updates.
Acceptance
Accept/merge when the agreed requirements are met and your validation steps pass.
If acceptance is blocked, provide a short list of remaining required changes so contributors can close the gap quickly.
Example decision record
After reviewing a bug fix, the maintainer can comment: “The regression test passes, the reported case is fixed, and the documented manual check succeeded. Accepted for the agreed issue scope.” If a check fails, name it and explain the change needed before acceptance.
Keep payment aligned with review
Acceptance is the decision that the delivered work meets the agreed scope. Before releasing a bounty, confirm the contributor, amount, and task. If new work is requested, agree on scope and funding first. A team should identify who makes the final acceptance decision.
