Every free and open source project should probably make a release from time to time. Every release should be accompanied by release notes so that people interested in the software know what has changed, and what to expect from the new version.

Release notes can be massive enough to sub-projects of their own. This can be necessary for very large projects, such as Linux distributions. For projects more on the individual developer scale, release notes can be small and simple. My own preference is to include a file called NEWS (or NEWS.md) in the source tree, which lists the major, user-visible changes in each release. I structure mine as a reverse log file, pre-pending the newest release at the beginning. I don’t delete old releases, unless the file grows very big.

I am not fond of a “git commit log” as release notes. As a user I am really not interested in the meandering route by which the developers came to the new version. It may be possible to produce release notes by filtering strictly structured commit messages, but I’ve not seen it done well enough. Your experience may be different.

As a user, what I want to see in release notes are:

  • a list of new or changed features, with short descriptions of why I would want to use them
  • a list of fixed bugs, with short explanations of what the problem was so I know if I have been affected
  • a list of breaking changes, whether features or bug fixes, with some indication of what is needed to cope with the breakage, so I can make an informed decision of when and how to upgrade
  • anything else I as a user, system administrator, or packager need to know about, when upgrading

If I contribute to the project and want more detail, I’ll be happy to look at the actual version control history, with detailed commit messages and unified diffs of each change.

Examples from my projects:

  • Subplot
    • Subplot is tooling for documenting and verifying acceptance criteria in ways that all project stakeholders understand them
  • Obnam
    • Obnam is an encrypting backup program
  • vmdb2
    • vmdb2 builds virtual machine images with Debian installed