✍️ Writing
Breaking-API Changelog Pull Request Template (No Invented Versions)
Write a GitHub PR body template for a breaking API change from a spec. No invented versions, sunset dates, or traffic stats.
0Reviews
Prompt
Act as an API program manager writing a GitHub pull-request body for a breaking API change. You write a GitHub PR template and a filled example body from a breaking-change spec. You do not invent a version number, a sunset date, a traffic percentage, or a successor path. This is not a Keep a Changelog dump, not a customer deprecation email, and not a git log rewrite. You work only from Inputs. Do not invent stats, citations, quotes, URLs, names, IDs, or records that are not in Inputs. Inputs: - Repo and default branch: [Repo] - PR title I already want (or NONE): [Title] - Pasted spec or design note for the break: [Spec] - Endpoints, fields, or headers that break (quote Spec): [Breaks] - Replacement I can prove (or NONE): [Replacement] - Version bump I can prove (semver as already decided): [Version or NONE] - Migration steps I can prove: [Steps] - Checks that must stay green: [Checks] - Reviewers or CODEOWNERS teams I may @ (or NONE): [Reviewers] - Words I must not use: [Banned] Generate: 1. Honesty ledger: repo, breaks, replacement, version, checks, reviewers. Forbidden: any version, sunset, or successor not in Inputs. 2. PR title (72 chars max). Reuse Title if given. Else build from Breaks only. Print the count. Do not put a version in the title unless Version is not NONE. 3. Template markdown: ## Summary, ## Breaking change, ## Replacement, ## Migration, ## Test plan, ## Rollback. Empty sections stay as HTML comments, not invented prose. 4. Filled example body using only Spec, Breaks, Replacement, Version, Steps, Checks. 5. Checklist: each Checks item as a box. If Checks is empty, write no CI names in Inputs. 6. Reviewer line: only Reviewers. If NONE, write no reviewers named. 7. What this PR is not: customer deprecation notice, Keep a Changelog file, git log. Say so in a footer. 8. Compliance pass: quote Banned words, invented versions, invented sunset dates. Cut them. Constraints: - GitHub PR body for a breaking API change. Not a customer deprecation notice and not Keep a Changelog. - Never invent a version, sunset date, replacement path, or traffic share. - If Version is NONE, write version not specified rather than bumping semver. - Do not @ teams that are not in Reviewers. - No emojis.
Instructions
Replace every [bracket] with your details before running. Works on ChatGPT, Claude, and Gemini.
Examples
Example Input
Repo: northwind/pay-api, branch main
Title: NONE
Spec: 2026-08-20 design note: GET /v3/invoices/{id}/pdf will error 410 once the documents path is required. Header X-Invoice-Legacy still accepted. POST /v3/invoices unchanged. No version bump decided. No sunset date.
Breaks: GET /v3/invoices/{id}/pdf returns 410 in this PR when feature flag pdf_legacy is off
Replacement: GET /v3/documents/{id}?type=invoice_pdf already shipped in v3.9.0
Version: NONE (release train not numbered)
Steps: flip flag pdf_legacy off in staging; clients should call /v3/documents; keep X-Invoice-Legacy; no SDK bump named
Checks: pay-api-ci / lint; pay-api-ci / test; contract-pdf-path
Reviewers: @northwind/billing-eng
Banned: v4.0.0, Friday sunset, 12 percent of traffic, BREAKING in all caps as a versionExample Output
1. Ledger. northwind/pay-api main. Breaks: GET /v3/invoices/{id}/pdf 410 when pdf_legacy off. Replacement: GET /v3/documents/{id}?type=invoice_pdf (v3.9.0). Version: NONE. Checks: lint, test, contract-pdf-path. Reviewers: @northwind/billing-eng. Forbidden: v4.0.0, Friday sunset, 12 percent, invented SDK.
2. Title. Return 410 on legacy invoice PDF path (46). No version in title.
3. Template. ## Summary. ## Breaking change. ## Replacement. ## Migration. ## Test plan. ## Rollback. HTML comments mark empty optional fields (release version, sunset) rather than filling them.
4. Filled body. Summary: this PR returns 410 on GET /v3/invoices/{id}/pdf when flag pdf_legacy is off. POST /v3/invoices unchanged. X-Invoice-Legacy still accepted. Breaking change: quote Breaks. Replacement: documents path from v3.9.0. Version: not specified. Migration: staging flag off; clients call /v3/documents; keep header; SDK bump NOT IN INPUTS. Test plan: the three checks. Rollback: restore pdf_legacy on. Not a customer email.
5. Checklist. [ ] pay-api-ci / lint [ ] pay-api-ci / test [ ] contract-pdf-path.
6. Reviewers. @northwind/billing-eng only.
7. Footer. This is a PR body, not Keep a Changelog and not a deprecation notice.
8. Compliance. Cut: v4.0.0, Friday sunset, 12 percent of traffic. Gaps: release version, sunset, SDK, flag default in prod.
Missing-data policy: if a field was blank, write NOT IN INPUTS rather than guessing. Lock any tool version named in Inputs; if unnamed, write unknown. No invented testimonials, star ratings, or press logos. If legal, clinical, insurance, HR, education-plan, or veterinary content appears, add a one-line not-advice and de-identify banner. Quote banned-word hits and cut them. End with a gaps list of five bullets the user still owes you. Character and byte caps in the job are hard; print counts when relevant. Refuse to backfill DOIs, exam dumps, PHI, PII, or compensation promises not in Inputs.