The task
Friday 4 PM, sprint ends Monday. You have a Jira “Done” column with 27 tickets, a git log with 92 commits half of which are “fix lint” or “wip rebase,” and a PM lead who wants a release-notes draft in their inbox before they leave. The user-facing changes are real — a new bulk-import flow, faster search, a fix for the export crash that has been embarrassing — but they are buried under “refactor auth middleware” and “bump deps.” You need release notes that read like the product got better, not that the team was busy.
Where AI helps — and where it does not
AI is genuinely good at translating engineering-internal language (“refactored auth middleware”) into user benefit (“faster, more reliable sign-in”), at grouping 30 commits into 5-7 user-visible buckets, and at maintaining a consistent voice across “New / Improved / Fixed” sections. It also handles the “skip the dependency bumps” filter well — most internal noise is easy to drop if you tell the model what counts as user-facing.
What AI cannot reliably do: decide what is a breaking change worth surfacing. That requires release-management context — which API contract has external dependents, whether a UI shift will retrain users, what your support team has bandwidth to absorb. Always mark breaking changes manually before passing to AI, or they hide inside “Improved” and you find out when support tickets spike.
A specific failure mode: AI will gladly invent benefit language for tickets where the user benefit is unclear (“improved data layer” → “faster, smoother experience” with no actual perf claim). Tell it: “If a ticket has no clear user-facing benefit, drop it entirely. Do not invent a benefit.”
What to feed the AI
- The full changelog or Jira export (verbatim — model picks up labels, components, severity)
- Your audience tier: end-user app, prosumer tool, developer API, or all three (mixed audiences need separate notes)
- Brand voice — formal, casual, dry, playful — with one sentence example
- Breaking changes, manually pre-flagged with
[BREAKING](anything that requires user migration, retraining, or new permissions) - Items you want surfaced even if small (a long-promised fix, an issue that had its own GitHub thread)
- Items you want suppressed (security patches you have not yet disclosed, beta features still gated)
- Last release’s notes (for voice continuity and so the model does not re-announce the same thing twice)
- The single user benefit you most want highlighted in the headline (the “if they only read one line” item)
Copy-ready prompt
You are writing release notes for {product}, version {x.y.z}.
Audience: {end-user / prosumer / developer}.
Voice: {brand voice + one example sentence}.
Last release's notes (for continuity, not for re-announcing): {paste}
Headline benefit (the one item if they read one line): {item}
Breaking changes (pre-flagged, surface at top with migration steps): {list}
Changelog: {paste full export}
Output structure:
1) Headline — one sentence, lead with the single biggest benefit. No version number in the headline.
2) Breaking changes (if any) — pinned at top, each with: what changed, who is affected, migration step. Skip the section entirely if none.
3) New — 2-4 items. Each one sentence in user language, ≤25 words. Lead with the verb the user can now do, not the feature name.
4) Improved — 2-4 items. Same format. If the improvement has a number (faster by X, smaller by Y), include it.
5) Fixed — 2-4 items. User-visible bugs only — no internal-only fixes. Lead with the symptom the user noticed, not the cause.
Rules:
- If a ticket has no clear user-facing benefit, drop it. Do not invent benefits.
- Group related commits into one item ("export crash fix" + "export PDF formatting fix" = "Fixes for export reliability").
- No "Bug fixes and improvements" placeholder anywhere.
- Each item must earn its line; merge or cut redundant entries.Shorter variant — single-paragraph patch note
This is a patch release ({x.y.z}). Write a 60-word paragraph covering the 1-2 user-visible changes only. Lead with the symptom users noticed. Skip the New / Improved / Fixed structure — one paragraph is enough. Voice: {brand}.
Changelog: {paste}Sample output
A useful headline + breaking change block:
“Bulk import is here, and search is roughly 3x faster on accounts with more than 10K items.
Breaking change — API v1.4: the /exports endpoint now returns download_url instead of file_path. Existing integrations break on Nov 14. Migration: replace file_path references with download_url (the value format is identical). One-line code change. Reach out if you need a longer window.”
A useful “New” item: “Import up to 10,000 rows at once from CSV or Google Sheets — no more 500-row batching. Validation runs in the background so you can keep working.”
A useful “Fixed” item: “Exports no longer crash when a project name contains an emoji or colon. The crash hit roughly 4% of exports; if your last attempt failed silently, please try again.”
How to refine
- Lead with the verb the user can do: “Rewrite each item to lead with the action the user can now take, not the feature name. ‘Bulk-import 10,000 rows’ beats ‘Bulk import feature is now available.’”
- Drop benefit-less items: “Re-read the changelog and remove any item where the user benefit is implied or hand-waved. If we cannot say what changes for the user in one short sentence, the item does not belong here.”
- Surface numbers where you have them: “If a change has a measurable improvement (speed, size, accuracy), include the number. ‘Search is faster’ is filler; ‘Search is roughly 3x faster on accounts over 10K items’ is signal.”
- Pin breaking changes properly: “Move every
[BREAKING]item to the top with a migration step and a date. They cannot live inside the ‘Improved’ section; that is how support tickets are made.” - Cut to 5-7 items per section: “Cap each section at 5-7 items. If we have more, the lower-priority ones go in the dropdown ‘See all changes’ link. Long lists train users to skim.”
Common mistakes
- “Bug fixes and improvements” as a placeholder — signals zero care; even one specific fix is better
- Internal naming leaking in — “OAuth middleware refactor” means nothing to users; translate every term to user language before shipping
- Breaking changes buried inside “Improved” — biggest source of post-release support spike; pin them at top with migration steps
- Inventing user benefits for unclear tickets — the model will gladly do this; tell it to drop unclear items
- Re-announcing last release’s items — happens when you do not feed the model last release’s notes for continuity
- Listing 30 items because the changelog had 30 — users do not read past 7; the rest belong in a “See all” link
- Skipping the brand voice example — without it, the model defaults to a generic SaaS voice that does not sound like your product
- Posting the AI draft unedited — release notes are a brand surface; one human editorial pass for tone and accuracy is non-negotiable
FAQ
- How often should I ship release notes?: Per release for product-facing changes (weekly or biweekly is healthy). Combine into a quarterly “What’s new” digest for marketing surfaces and email.
- Should I include patch notes?: For developer-facing products and API consumers, yes — they expect to see every behavioral change. For end-users, only when the patch is user-visible (a crash fix, a UI regression). Internal patches do not need a note.
- What about screenshots and GIFs?: Useful for “New” items (especially flows users have to discover); skip for “Fixed” items where the value is “thing now works.” A GIF replaces 50 words of description for any visual flow.
- Where do release notes live — app, blog, or both?: Both, with one canonical version. The blog post is canonical; the in-app changelog links to it. Search and SEO need the long-form; in-app needs the short list.
- What if our team does not write tickets in a release-notes-friendly way?: Add a release-notes label to the tickets that count, and write a one-line “for release notes” field as part of definition-of-done. The 30 seconds at ticket close saves 20 minutes at release time.