How to Write a Breaking-API Changelog Pull Request Template
PR templates go wrong when they mint v4.0.0 and a Friday sunset the spec never named. The version field was NONE. Leave it blank.
The matching generator is the Breaking-API Changelog Pull Request Template (No Invented Versions) prompt. Browse related cards in the PromptDig library (Browse more prompts). When a filled run survives, share the version you actually use (Share a prompt).
Ledger breaks and versions before the title
Write a GitHub PR body template for a breaking API change from a spec. No invented versions, sunset dates, or traffic stats. Start by filling Inputs, not by asking the model to remember last week's run. If a field is blank, write NONE or NOT IN INPUTS and leave it blank through Generate. The card is built so the model cannot honestly invent a number, owner, URL, or command that you did not paste.
Paste these fields before you hit run:
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]
That inventory is the honesty ledger. Anything that does not appear there is forbidden in the draft. If you catch yourself adding a nice-to-have after the run, you are no longer using the card. You are ghostwriting. Put the extra fact in Inputs and run again.
Keep it a PR body, not a customer deprecation notice
Generate is numbered on purpose. Do not skip a step because the first paragraph looked done. The early steps exist to stop later prose from smuggling claims.
Walk the Generate list in order:
- Honesty ledger: repo, breaks, replacement, version, checks, reviewers. Forbidden: any version, sunset, or successor not in Inputs.
- 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.
- Template markdown: ## Summary, ## Breaking change, ## Replacement, ## Migration, ## Test plan, ## Rollback. Empty sections stay as HTML comments, not invented prose.
- Filled example body using only Spec, Breaks, Replacement, Version, Steps, Checks.
- Checklist: each Checks item as a box. If Checks is empty, write no CI names in Inputs.
- Reviewer line: only Reviewers. If NONE, write no reviewers named.
- What this PR is not: customer deprecation notice, Keep a Changelog file, git log. Say so in a footer.
- Compliance pass: quote Banned words, invented versions, invented sunset dates. Cut them.
If a step asks for a version lock, quote the version from Inputs in the output. If a step asks for a refuse list, keep the refuse list in the published artifact, not in a sidebar you delete. Reviewers should see what the model was not allowed to do.
If Version is NONE, do not bump semver
Most failures are the same shape: a missing field gets a confident fill. A conversion rate appears. A Gradle task appears. A flash point appears. A caption appears on a job that asked for slide text only. Your review is to search the draft for numbers, names, and commands, then grep Inputs. No match means cut.
Honor the constraints as hard stops, not vibes:
- 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.
When the card says not legal advice, not certification, not an exam dump, or not a caption engine, that sentence belongs at the top of the output. Deleting it to look more finished is how you inherit risk.
Checklist only the CI names you pasted
Finish with the compliance pass the prompt already asks for. Quote the banned-word hits. Cut them. Print character counts when the job has a cap. Print word counts when the job has a budget. List gaps as gaps. Five missing facts are more useful than one smooth paragraph.
Tags on the card (breaking api pr template, changelog pull request body, no invented api versions) are a reminder of the job shape, not an invitation to wander into a neighboring cluster. If you need a different surface, open a different PromptDig card rather than stretching this one.
Fill the card, then run
Replace every bracket. Run on ChatGPT, Claude, or Gemini. Read the ledger first, then the artifact. If the model invents a commit, KPI, DOI, PEL, bid, or logo, discard the run. Tighten Inputs. Run again. Share the filled card that survived, not the first draft that sounded done.