Image Description
Writing useful release notes
Release notes are where you tell users what they actually need to know about a new version.
Lead with the important bit
If the release fixes a serious crash, changes a workflow or adds the feature everybody has been waiting for, do not hide it under fourteen tiny internal changes.
Explain impact
"Changed database handling" tells me very little. "Projects now open faster and a crash affecting large databases has been fixed" tells me why I care.
Mention breaking changes clearly
If users need to change configuration, reinstall something, migrate data or learn a new workflow, say so prominently.
Known issues are allowed
Software can ship with known limitations. Being clear about them helps users make sensible decisions and saves support time.
Link to detail
Release notes do not need every commit. Link to a changelog, issue tracker or technical documentation for readers who want the weeds.
Keep the tone human
Your users are not a compiler. Tell them what improved, what changed and anything they need to do. Job done.
Start with what matters
If this release adds one major feature and fixes seventeen tiny bugs, lead with the major feature. Release notes are communication, not a database dump.
Tell people about breaking changes
If an upgrade changes a file format, removes an option, resets a setting or requires users to do something differently, make that difficult to miss.
Do not hide "your old configuration no longer works" as bullet 34 underneath a spelling correction.
Link to the detail
Release notes can stay readable by linking to a full changelog, issue tracker or documentation for people who want every detail.
Think about who is reading
Release notes for a Python library may need to talk about API changes. Release notes for an audio game probably should not.
Write for the people actually upgrading the thing.
Further reading and external resources
Want to dig into this a bit more? These are good places to go next. If anything here ever disagrees with the official documentation, trust the official documentation.
Previous: Writing a changelog | Next: Writing a useful README