Release Notes Generator Rules

# Release Notes Rules Input: a commit range, PR list, or diff summary. Output: release notes for users of the product, not for its committers. ## Selection and grouping - Group every entry under exactly one of these headings, in this order, omitting empty sections: **Breaking changes**, **New**, **Improved**, **Fixed**, **Deprecated**. No "Misc", no "Chores", no "Other". - Exclude entirely: dependency bumps without user-visible effect, refactors, test-only changes, CI changes, formatting commits, and reverts of unreleased commits. If a release would be empty after exclusions, say "Maintenance release, no user-facing changes" and stop. - Merge multiple commits that ship one feature into one entry. Readers care about the feature, not your commit granularity. - Order entries within a section by how many users they affect, most first — not by commit date. - Cap normal releases at ~10 entries. Past that, keep the top items and end the section with a one-line link: "Plus N smaller fixes — full list in the compare view." ## User-impact framing - Every entry states what changed for the reader, starting with the outcome: "CSV exports now include header rows" — never "Refactored export module" or "Updated CSVWriter class". - Translate internals to behavior. `fix: race in token refresh` becomes "Fixed intermittent logouts during long sessions." If you cannot name the user-visible effect of a commit, leave the commit out. - Name the conditions under which a fix applies: "Fixed crash when importing files over 100 MB", not "Fixed import crash". - One sentence per entry, ≤20 words, starting with a verb in past tense for fixes ("Fixed", "Restored") and present for capabilities ("Adds", "Supports"). No trailing periods on single-sentence entries — pick one convention per project and keep it. - Link each entry to its PR or issue in parentheses at the end: `(#482)`. - Banned words: "various", "minor", "miscellaneous", "improvements and bug fixes" (as a standalone entry), "enhanced", "robust", and any superlative about your own code. ## Breaking changes - Breaking changes always come first, under their own heading, even if there is only one — never folded into "Improved". - Each breaking entry has three parts: what broke (one sentence), who is affected (one sentence naming the API/flag/config touched), and the migration (exact before/after, as code or config, not prose like "update your configuration accordingly"). - A renamed or removed option must show the old name and the new name: "`--concurrency` is removed; use `--jobs N`." - If there are breaking changes, the version bump must be major (under semver) — flag the mismatch instead of writing the notes if it is not. - Deprecations state the removal version: "Deprecated `legacyAuth`; it will be removed in 4.0." ## Header and tone - Header: version, date (YYYY-MM-DD), and — only if the release has a theme — one plain sentence stating it. No codenames, no exclamation marks, no "we're excited". - Write for a reader deciding whether to upgrade in the next five minutes. Every sentence either helps that decision or gets cut. - Credit external contributors by handle on their entries ("thanks @handle"); never credit maintainers or bots. - Before finishing, re-read the draft as a user of the previous version and delete any entry that does not tell them something they can see, do, or must change.