Writing good release notes

As the developer of a software package, you have just finished preparing a shiny new release. No matter how big the release is, you obviously want your users to upgrade so that they can experience all the new features and bug fixes — or, rather, witness the results of your hard work. But how do you convince them to do so?

One of the first things to do is ensure that your release notes are of great quality. Let's see how and where to put them.

The NEWS file

If you are distributing your application as a source package, it is customary to include a NEWS file that showcases the major changes since the previous release. You want this file to:

1. outline the purpose of the new release;
2. describe high-level changes that the user will experience along with pointers to more information;
3. mention any possible incompatibilities with the previous release and what the upgrade path is; and
4. include an entry for every single past release.

As usual, pay very close attention to grammar, spelling and formatting. Of all distribution documents in your package, this will be the one most looked at and whatever you write in it is your demonstration of the work that went into the release.

A common mistake is to treat the commit log of the project (or the ChangeLog file) as a replacement for manually-crafted news items. This is bad: commit logs are of no interest to end users seeking information about a new release, if only because they include too much detail.

The web site

Many software hosting sites allow you to upload release files and let you attach release notes to them. Because these are looked at even before the downloading the package, it is even more important that they are up-to-date and easy to find.

An option to fill these notes is to just copy/paste the contents of the NEWS file and possibly adjust the formatting. If the entry in the NEWS file was properly written, this should be enough.

In my previous role as a packager, I witnessed plenty of source packages that included really poor release notes, if they existed at all. I was forced to upgrade the packages to a newer versions only because some other package required them... but then I could not justify why the upgrade was important.

Keep the packagers happy and your software will reach more packaging systems which, in turn, translate to more end users.