Estimated time: 5–10 min

Pull Request Checklist

A practical pre-submission checklist for developers to self-audit diffs, clean up code, and provide context before asking team members for a review.

#Pull Request#PR#GitHub#GitLab#Self-Review#Code Review#Pre-flight

PR Category:

Phase Preset:

Progress:0%0 of 48 completed

1. Scope & Diff Boundaries

Keep the pull request focused, readable, and atomic for fast review.

0/4 checks

PR has one single, coherent purposeBlockingAuthor

Unrelated formatting or drive-by edits removedBlockingAuthor

Total diff size is reasonable (<250 lines preferred)ImportantAuthor

Auto-generated files verified as intentionalImportantAuthor

2. Author Self-Review & Code Hygiene

Perform a thorough self-audit of your own diff before asking others for their time.

0/5 checks

Author has personally read through the entire Git diffBlockingAuthor

Temporary console.log, print(), or debugger statements removedBlockingAuthor

Commented-out dead code blocks deletedBlockingAuthor

Accidental scratch files or local configs removedBlockingAuthor

TODO and FIXME comments audited & ticketedImportantAuthor

3. Feature Correctness & Edge Case Verification

Verify functional correctness, expected user flows, and error handling.

0/4 checks

Requested feature requirements & acceptance criteria satisfiedBlockingAuthor

Main user interaction flow manually tested locallyBlockingAuthor

Edge cases & boundary values evaluatedImportantAuthor

Error states & failure responses verifiedImportantAuthor

4. Automated Test Coverage

Ensure automated unit, integration, or regression tests validate the changes.

0/4 checks

Relevant unit or integration tests added/updatedBlockingAuthor

All automated test suites pass locallyBlockingAuthor

Regression test included for fixed bugBlockingAuthor

Flaky or brittle test patterns avoidedImportantAuthor

5. Local Build, Lint & CI Pipeline Health

Confirm build compilation, linting rules, and type checking succeed.

0/4 checks

Production build completes locally without errorsBlockingAuthor

Linter and code formatter checks passBlockingAuthor

Type checker completes with zero errorsBlockingAuthor

CI pipeline expected to pass greenBlockingAuthor

6. Database Migrations & Environment Config

Document schema changes, environment variables, and deployment dependencies.

0/4 checks

Database schema migration scripts included & testedBlockingAuthor

Backward compatibility of database change verifiedBlockingAuthor

New environment variables documented in .env.exampleBlockingAuthor

Deployment execution order notedImportantAuthor

7. Documentation & Release Notes

Keep technical documentation, API specifications, and changelogs up to date.

0/4 checks

Public & internal API documentation updatedImportantAuthor

Project README or setup guides updatedImportantAuthor

Code comments added for non-obvious algorithmsSuggestionAuthor

CHANGELOG entry added if applicableNitAuthor

8. PR Description & Context Quality

Provide reviewers with clear context, testing instructions, and decision rationales.

0/5 checks

PR description explains WHAT changed and WHYBlockingAuthor

Clear 'How to Test' step-by-step instructions providedBlockingAuthor

Screenshots or visual demo attached for UI changesBlockingAuthor

Related issue ticket numbers linked (Closes #123)ImportantAuthor

Known trade-offs & follow-up tasks disclosedImportantAuthor

9. Reviewer Orientation & Highlighted Areas

Guide reviewers through complex diffs and call out specific questions.

0/4 checks

Appropriate primary reviewers & domain owners assignedBlockingAuthor

Line comments added on diff to explain complex structural changesImportantAuthor

Key architecture decisions explained in PR threadImportantAuthor

Specific feedback questions explicitly called outSuggestionAuthor

10. Security & Performance Gate Checks

Self-audit high-risk security boundaries and performance bottlenecks.

0/4 checks

Checked for hardcoded secrets & private tokensBlockingAuthor

User input validated against SQL/XSS/Command injectionBlockingAuthor

Backend authorization & tenant boundaries verifiedBlockingAuthor

Performance impact evaluated (No N+1 queries)ImportantAuthor

11. Final Pre-Submission Readiness

Ensure branch cleanliness, green CI, and clear title before requesting review.

0/6 checks

Rebased onto target branch with zero merge conflictsBlockingAuthor

Commit history cleaned & formatted cleanlyImportantAuthor

Draft status removed when ready for reviewBlockingAuthor

PR title is clear & follows team prefix conventionBlockingAuthor

CI build status is greenBlockingAuthor

Linked to dedicated Security & Code Review checklists for deep auditsNitAuthor

Author vs Reviewer Role Division

The Difference Between PR Preparation & Code Review

A successful code review starts before the reviewer ever opens the PR. Distinguish the author's pre-flight responsibilities from the reviewer's evaluation role:

Author Responsibility (Pre-Flight)

Self-review entire diff to catch leftover console.log and dead code.
Ensure local build, linter, unit tests, and CI pass green.
Write a clear description detailing What, Why, and How to Test.
Keep the PR atomic and focused (<250 lines changed preferred).
Attach before/after screenshots for visual UI modifications.

Reviewer Responsibility (Evaluation)

Evaluate overall architecture, design patterns, and maintainability.
Verify edge cases, security boundaries (auth/IDOR), and data safety.
Check performance bottlenecks and N+1 query risks.
Provide constructive, empathetic feedback and request clear changes.
Approve when code meets team standards without demanding perfection.

Velocity Rationale

Why Small Pull Requests Get Merged 3x Faster

Research across engineering teams consistently shows that reviewer response time and defect detection rate depend heavily on PR diff size:

< 200 Lines

Fast & Deep Review

Reviewed within 2–4 hours. Reviewers read logic line-by-line and catch subtle edge-case bugs.

200 – 500 Lines

Moderate Latency

Reviewed within 12–24 hours. Requires dedicated focus blocks; feedback quality starts to decay.

> 500 Lines

Stalled & Superficial

Sits in queue for days. Reviewers skim diffs, leading to superficial approvals and missed bugs.

PR Description Template

Anatomy of a Great Pull Request Description

A well-structured PR description provides immediate context and lets reviewers verify your changes in minutes:

## Summary

Brief 2-3 sentence explanation of what changed and why. (Closes #142)

## How to Test

1. Checkout branch `feature/user-export`

2. Run `npm run dev` and navigate to `/settings/privacy`

3. Click "Export My Data" and verify JSON download completes in <2s

## Visual Demos (if applicable)

[Attach screenshot or short GIF demonstrating UI state changes]

## Key Decisions & Trade-offs

- Used async background worker queue for export processing to avoid API timeouts.

When to Use This Checklist

Immediately before marking a Draft PR as ready or clicking 'Request Review' on GitHub/GitLab.
To self-audit diff size, remove leftover debug logs, and verify test coverage before peer review.
When preparing feature PRs, bugfixes, or database migrations to ensure clear reviewer context.
To ensure your PR description contains clear 'How to Test' instructions and visual demos.

Common Pitfalls to Avoid

Bundling unrelated bugfixes, formatting changes, and refactoring into a single 1,200-line PR.
Leaving console.log, debugger;, or commented-out code snippets in the final commit history.
Requesting review without writing a PR description, forcing reviewers to reverse-engineer intent from raw diffs.
Not testing the branch locally against the latest main branch before opening the PR.
Failing to disclose known compromises or trade-offs made in the implementation.