Image Description
Writing useful release notes
Release notes answer a fairly simple question: I already use this thing, so what changed?
They are not a dump of every commit you made since the last version. They are the useful bit between "version 2.4 is out" and making somebody inspect the repository to discover why they should care.
Lead with the thing people will notice
If the release adds one major feature and fixes seventeen tiny bugs, lead with the feature.
If it fixes a crash that has been annoying everybody for three months, lead with that instead.
Release notes are communication, not a database dump.
Explain the effect, not just the implementation
Changed database handling may be perfectly accurate and still tell the user almost nothing.
Large projects now open faster, and a crash while loading some databases has been fixed explains the result.
The technical detail can live in the changelog, issue tracker or commit history if somebody needs it.
Make breaking changes difficult to miss
If an upgrade changes a file format, removes an option, resets a setting, requires a migration or changes a familiar workflow, say so prominently.
Do not hide "your old configuration no longer works" as bullet 34 underneath a spelling correction.
Known issues are allowed
Software can ship with known limitations. Pretending otherwise does not remove them.
If a known problem is likely to affect people, mention it and give a workaround if one exists. That helps users make sensible decisions and may save you answering the same support question repeatedly.
A small example
Suppose version 1.4 adds automatic project backups, improves startup time and has one known problem with importing older settings.
The useful release note is something like:
Version 1.4 adds automatic project backups and improves startup time. It also fixes a crash when opening projects containing empty categories.
Known issue: settings exported by versions earlier than 1.0 may not import correctly. If you rely on an older settings file, keep your previous installation until you have checked the import.
That is enough to tell somebody what is new, what was fixed and whether upgrading has a catch.
Changelog or release notes?
A changelog is the ongoing record of changes across versions. Release notes are the message for this release.
They can overlap. They just have different jobs.
Write for whoever is upgrading
Release notes for a Python library may need to discuss API changes. Release notes for an audio game probably should not.
Your users are not a compiler. Tell them what improved, what changed and anything they need to do. Job done.
Further reading and external resources
Previous: Writing a changelog | Next: Writing a useful README