Product changelog

Users can follow it, and know what this release means for them

Write a changelog from the change list below. The readers are ordinary users who already use the product. Structure: 1) one sentence on the most notable change in this release; 2) grouped as 'New / Improved / Fixed', each entry saying 'what changed plus what it means for you', with no internal jargon; 3) a separate list of things users have to do themselves (sign in again, change a setting); 4) known issues. Do not write empty phrases like 'we improved the user experience'.

[paste the change list]

How to use

When you are done, cover the 'what it means for you' column and read it back — if it does not parse, you are still writing from the inside.

Good for

There are twenty-odd commits in this release and three of them change how users work: that has to be clear before it ships.
Support will answer questions from this changelog: if it is vague, they will invent an explanation for the user.

Not for

An internal engineering retrospective: that needs commit references and trade-offs, which a user-facing changelog erases by design.
The release includes a pricing or terms change: a changelog cannot carry that, it needs its own notice and consent flow.

Example

Input

fix: CSV export garbled Chinese characters / feat: change avatar from mobile / breaking: session lifetime cut from 30 days to 7

What you get

Opens with 'if you have not opened the app in 7 days, you will sign in again'; grouped as new/improved/fixed with a line of impact each ('change your avatar without going back to a laptop'); a separate what-you-need-to-do section; no 'improved the experience'.

Common mistakes

Pasting the raw commit list: 'refactor: extract useAuth hook' comes back as a sentence no user understands, or gets spun into a compliment.
Listing changes without impact: users learn the session lifetime changed but not that they will be signed out tomorrow, and support hears about it the next day.

Try tweaking it like this

Change 'group as new/improved/fixed' to 'top three only' when this goes in an in-app modal rather than a docs page.
Add 'one line per item on what happens if you do nothing' when the release touches settings or permissions.