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).

1. 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.

1. 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".

1. 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."

1. 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").

1. 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.