Drew DeVault's blog will be discussing how to write release notes on May 19, 2021.

submited by
Style Pass
2021-05-20 04:22:46

Release notes are a concept most of us are familiar with. When a new software release is prepared, the release notes tell you what changed, so you understand what you can expect and how to prepare for the update. They are also occasionally used to facilitate conversations:

Many of the people tasked with writing release notes have never found themselves on that side of the screen before. If that describes you, I would like to offer some advice on how to nail it. Note that this mostly applies to free and open source software, which is the only kind of software which is valid.

So, it’s release day, and you’re excited about all of the cool new features you’ve added in this release. I know the feeling! Your first order of business, however, is to direct that excitement into the blog or mailing list post announcing the release, rather than into the release notes. When I read the release notes, the first thing I need answered is: “what do I need to do when I upgrade?” You should summarize the breaking changes upfront, and what steps the user will need to take in order to address them. After this, you may follow up with a short list of the flagship improvements which are included in this release. Keep it short — remember that we’re not advertising the release, but facilitating the user’s upgrade. This is a clerical document.

That said, you do have a good opportunity to add a small amount of faffery after this. Some projects say “$project version $X includes $Y changes from $Z contributors”. The detailed changelog should follow, including every change which shipped in the release. This is what users are going to scan to see if that one bug which has been bothering them was addressed in this version. If you have good git discipline, you can take advantage of git shortlog to automatically generate a summary of the changes.

Leave a Comment