Back to Markdown Style Guide — Read the style guide first for formatting, citation, and emoji rules.
Use this template for: Documenting pull requests as persistent, searchable markdown records. This file IS the PR — not a companion document. It captures everything: what changed, why, how to verify, security impact, deployment strategy, and what was learned.
Key features: Summary with impact classification, change inventory with before/after, testing evidence, security review, breaking change documentation, deployment strategy, observability plan, rollback plan, and reviewer checklist.
Philosophy: This file IS the PR description — not a companion, not a supplement, not a copy. The GitHub PR is a thin pointer: humans go there to comment on diffs, approve, and watch CI. But the actual record — what changed, why it changed, testing evidence, rollback plan, and lessons learned — lives HERE, committed to the repo.
When someone asks "what was PR #123 about?" six months from now, they grep docs/project/pr/, not the GitHub API. When you migrate from GitHub to GitLab, every PR record comes with you. When an AI agent needs to understand the history of a module, it reads these files locally — no tokens, no rate limits, no platform dependency.
This is the Everything is Code philosophy: project management data lives in the repo, versioned and portable. Don't capture information in GitHub's UI that should be captured in this file. Invest the 10 minutes. A great PR file eliminates the "what was this PR about?" Slack message and the "can someone check the GitHub PR?" context switch — the answer is already in the repo.
docs/project/pr/pr-00000123-fix-auth-timeout.md
docs/project/pr/pr-00000124-add-job-retry-metrics.md
docs/project/pr/pr-00000125-refactor-ci-stage-order.md
docs/project/pr/pr- + PR number zero-padded to 8 digits + - + short lowercase hyphenated descriptionhttps://github.com/<org>/<repo>/blob/<branch>/docs/project/pr/pr-00000123-fix-auth-timeout.md)Everything below the line is the template. Copy from here:
| Field | Value |
|---|---|
| PR | #NUMBER (add tracker URL if your project uses one) |
| Author | [Name] |
| Date | [YYYY-MM-DD] |
| Status | [Open / Merged / Closed] |
| Branch | [feature/branch-name] → main |
| Related issues | #ISSUE, #ISSUE2 |
| Deploy strategy | [Standard / Canary / Blue-green / Feature flag] |
[2–4 sentences. What this PR does at a business/product level, not code level. Why was this change necessary? What problem does it solve or what feature does it enable?]
| Dimension | Level | Notes |
|---|---|---|
| Risk | 🟢 Low / 🟡 Medium / 🔴 High | [Why this risk level] |
| Scope | [Narrow / Moderate / Broad] | [What areas are affected] |
| Reversibility | [Easily reversible / Requires migration / Irreversible] | [Rollback complexity] |
| Security | [None / Low / Medium / High] | [Auth, data, or permissions changes?] |
| File / Area | Change type | Description |
|---|---|---|
[path/to/file] |
[Added / Modified / Deleted / Renamed] | [What changed and why] |
[path/to/file] |
[Type] | [Description] |
[path/to/file] |
[Type] | [Description] |
[For behavioral changes, show the difference. Use code blocks, screenshots, or diagrams as appropriate.]
Before:
[Previous behavior, output, or code pattern]
After:
[New behavior, output, or code pattern]
[If this PR changes how components interact, include a diagram. Skip this section for small changes.]
flowchart LR
accTitle: Architecture Change
accDescr: How this PR modifies the component interaction pattern
a[⚙️ Component A] -->|New path| b[📦 Component B]
b --> c[💾 Data Store]
# Steps a reviewer can follow to test this change locally
[command 1]
[command 2]
[command 3 — with expected output]
| Test type | Status | Notes |
|---|---|---|
| Unit tests | ✅ Passing | [N new / N modified] |
| Integration tests | ✅ Passing | [Details] |
| Manual testing | ✅ Verified | [What was tested manually] |
| Performance | ⬜ N/A | [Or benchmark results if relevant] |
Security impact: [None / Low / Medium / High] — [Brief justification]
[If security-sensitive: Reviewed by: [security reviewer name, date]]
This PR introduces breaking changes: [Yes / No]
[If no, delete the rest of this section.]
| What breaks | Who's affected | Migration path |
|---|---|---|
| [API endpoint / behavior / config] | [Service / team / users] | [How to migrate] |
Before:
[Old usage, API call, config, or behavior]
After:
[New usage — what consumers need to change]
Deprecation timeline: [When the old behavior will be removed, if applicable]
[How to revert this change if something goes wrong in production.]
Revert command:
git revert [commit-sha]
Additional steps needed:
⚠️ Rollback risk: [Any caveats — data migration that's one-way, API consumers that may have adopted the new contract, etc.]
Approach: [Standard deploy / Canary (N% → 100%) / Blue-green / Feature flag]
Feature flags: [Flag name: [flag_name] — default: [off/on], rollout: [%/audience]]
[How do you know this deploy is healthy? Be specific: "p95 latency stays under 200ms, error rate stays below 0.1%, no new error types in logs for 1 hour."]
TODO or FIXME comments introduced without linked issues[Capture key review feedback and decisions made during the review process. This is the institutional memory — future developers will read this.]
Category: [Feature / Fix / Enhancement / Breaking / Security / Performance]
[One-line release note for changelog — written for end users, not developers]
Last updated: [Date]