Confirm the scope stays narrow
Start every review by verifying the pull request solves only the stated problem. When the description lists unrelated refactors or extra files, ask the author to split the work. Small, focused changes are easier to test and less likely to introduce hidden side effects. Reviewers can start by reading the description first. This prevents spending time on large diffs that could have been split. When multiple changes are needed, separate pull requests allow parallel work and clearer history.
Check that the title describes the change in plain language and that the body answers what changed, why it changed, and how to verify the result. Include links to related issues so reviewers can see the original requirement. Authors benefit from writing the description before they finish the code because it forces them to articulate the goal clearly. A mismatch between the written purpose and the actual diff is a reliable signal that the scope has drifted.
- One clear purpose per pull request
- No out-of-scope formatting or refactors
- Title and description match the diff
Verify tests cover the change
Tests must cover both the main path and the failure cases. If the author skipped new tests, the pull request description should explain why. Reviewers should confirm that existing tests still pass and that coverage did not drop for the modified files. When tests are present, the reviewer can run them locally or rely on the continuous integration results to confirm the expected behavior holds after the change.
Look for tests that validate behavior rather than implementation details. Fragile tests that break on every refactor add maintenance cost without protecting the code. A practical step is to ask the author to describe the scenarios they considered and to point to the specific test files that exercise those scenarios. This makes it easier to judge whether the test suite truly guards the modified logic.
- Tests for happy path and error cases
- No reduction in coverage for changed files
- Explanation provided when tests are omitted
Document risks and rollback steps
Every change carries some risk. The pull request should list any new dependencies, configuration changes, or migration steps. Reviewers need to know how to roll back if the deployment fails or if users report problems after release. Including a short rollback procedure in the description gives the team a ready plan instead of improvising under pressure.
When a change touches public APIs or contracts, the description must note compatibility impact and any required client updates. Feature flags or gradual rollout plans belong here as well. The checklist item prompts the author to think about what could go wrong and how the team would recover, which often surfaces issues that would otherwise appear only after merge.
- List of new dependencies or environment variables
- Rollback command or procedure
- Compatibility notes for APIs and clients
Attach screenshots and logs when useful
User interface changes, API responses, and infrastructure updates benefit from visual proof. Screenshots or short recordings let reviewers confirm the intended behavior without running the code locally. For non-visual changes, attach relevant log excerpts or example requests. This evidence also serves as a record for future contributors who need to understand why a decision was made.
Generated files and large diffs should be labeled so reviewers know they can skip them. Clear evidence reduces the chance of misunderstandings during review. A useful habit is to include before-and-after images for any visible change so the reviewer can judge whether the result matches the stated goal without additional context.
- Screenshots for UI or visual output
- Log snippets for error handling changes
- Labels on generated or large files
Run local checks before requesting review
Authors should run the project’s lint, test, and build commands locally and confirm the results in the pull request. This step catches obvious problems before reviewers spend time on them. When checks fail, the description should note the failure and the planned fix. The extra minute spent confirming a clean run saves multiple rounds of review comments later.
A short author checklist inside the template reminds contributors to self-review the diff, remove debug code, and update documentation before the pull request leaves draft status. This final pass often reveals small issues such as leftover console statements or outdated comments that would otherwise distract reviewers from the main change.
- Lint, tests, and build pass locally
- Debug code and temporary logs removed
- Documentation updated where needed