--- name: release-notes-format source: https://app.decimal.ai/s/release-notes-format@1/SKILL.md source_sha256: f647b58c9f30 --- # Release-notes format ## Contract Enforces the user-facing release-notes form on any change summary you turn into notes users read: lead with the highlights, group by user impact (New / Improved / Fixed), plain benefit language, and no internal churn. Apply to in-app "What's new", app-store notes, and customer changelogs; not to a developer CHANGELOG, commit messages, or an engineering status report. ## Rules 1. **Write for the user, lead with the highlight.** Order entries by how much the user will notice — the biggest new capability first. Never keep the order commits landed, and never open with an internal change (a refactor, a dependency bump). 2. **Group by user impact, not by developer changelog section.** Use these three buckets (or plain synonyms — Features / Improvements / Bug fixes): **New** for brand-new capabilities, **Improved** for existing things that got better or faster, **Fixed** for bugs the user hit. Do NOT reach for the developer-changelog set — Added / Changed / Deprecated / Removed / Security — that is a separate, engineer-facing convention. Skip any bucket that has no entries. 3. **Plain user language, never the commit line.** Rewrite each kept item as something the user understands. Strip the `feat:` / `fix:` / `chore:` prefix, the ticket ID, the module or function name, and the internal jargon. "feat: add CSV export endpoint to reports service" becomes "Export any report to CSV". 4. **State the benefit and the action.** Each entry says what the user can now do — and, when it helps, where to find it. "You can now schedule a report to email itself weekly — set it up under Reports → Schedule." Not just "Added scheduled reports." 5. **Omit internal-only churn.** Refactors, dependency bumps, CI and test changes, code cleanups, and performance work with no user-visible effect are left out entirely. If a performance change IS user-visible, describe the user benefit ("Dashboards load noticeably faster"), not the internal cause ("memoized the selector"). 6. **Present tense, second person.** Address the reader as "you"; describe changes in the present ("You can now…", "Search is faster"), not as past-tense engineering narration ("We refactored…", "Added support for…"). ## Worked examples A raw commit log (the base's dump-it default) and the conforming notes. ``` BEFORE (raw log, copied nearly verbatim) - feat: add bulk photo upload to the gallery - fix: crash when opening a shared album with no photos - refactor: split the uploader into its own module - chore: bump image-resize library to 2.4.0 - perf: cache thumbnail generation (server-side only) - feat: keyboard shortcuts for the photo editor - docs: update CONTRIBUTING AFTER (user-facing notes) New - Upload a whole batch of photos to a gallery at once, instead of one at a time. - Fly through edits with keyboard shortcuts — press ? in the editor to see them all. Fixed - Opening a shared album with nothing in it no longer crashes the app. ``` → The refactor, the library bump, the server-side cache, and the docs update are internal — dropped. The two features and the fix are regrouped by impact and rewritten in plain language. Turning a commit line into a user sentence: ``` BEFORE fix: null-check on invoice PDF generation (INV-812) AFTER Fixed: downloading an invoice no longer fails when a line item has no tax. ``` Past-tense engineering narration made present and user-facing: ``` BEFORE We added a new endpoint and refactored the notifications worker. AFTER New: you can now mute a single conversation without muting the whole channel. ``` Not the developer-changelog shape: ``` WRONG ## Added ## Changed ## Deprecated ## Removed RIGHT New · Improved · Fixed ``` ## Edge cases & exceptions - **A release with only bug fixes** → a single "Fixed" section is fine; do not invent features to fill "New". - **A breaking change the user must act on** → lead with it in plain terms and say what to do ("You'll need to reconnect your calendar once after updating"), not "BREAKING CHANGE:" jargon. - **A purely internal release** (all refactors and bumps, nothing user-visible) → the honest notes are a short "Under-the-hood improvements and fixes", not a list of internal commits. - **A security fix** → mention it plainly ("Fixed a security issue in file sharing") without the internal detail; group it under Fixed, not a separate developer "Security" heading. - **A moved or renamed feature** (a menu item relocated) → tell the user where it lives now, under Improved, not that an internal component was renamed. - **A change still behind a feature flag** and not yet on for users → leave it out until users can actually use it; unreleased work is not "what's new" for them. ## Do / Don't - Do lead with the biggest user-visible change. Don't open with a refactor or a dependency bump. - Do group under New / Improved / Fixed. Don't use Added / Changed / Deprecated / Removed. - Do rewrite each item in plain language. Don't paste the commit line with its `feat:` prefix. - Do state the benefit and where to find it. Don't just say a thing was added. - Do drop internal churn. Don't list refactors, bumps, CI, or tests. - Do write "You can now…" in present tense. Don't write "We refactored…" in the past. ## Common mistakes - Pasting the commit log almost verbatim, prefixes and ticket IDs included. - Listing refactors, dependency bumps, and CI changes the user cannot see. - One flat bullet list with no impact grouping. - Borrowing the developer CHANGELOG headings (Added / Changed / Removed) for a user audience. - Past-tense "We did X" narration instead of "You can now X". - Naming the module or function ("the AuthController") instead of the user-facing feature. ## Quick checklist - Leads with a user-visible highlight, not an internal change. - Grouped by impact: New / Improved / Fixed (not Added / Changed / Deprecated / Removed). - Each item in plain language — no `feat:`/`fix:` prefix, no ticket ID, no module name. - States the benefit and, where useful, where to find it. - Internal churn (refactors, bumps, CI, tests) omitted. - Second person, present tense.