Why you should have release notes
Building software is exciting. You get your first release out there, rock back your chair or celebrate with your team and overall everyone is happy. The word goes out and people start using what you’ve built. Exciting! Like any living software, you start improving your software and fix some bugs. There are a few times where I am looking at software (may it be a full blown application or plugins), I see that a new version is out, but I don’t see what has been changed. I also often come across releases where the major version has changed. As per semver, a major version means that one makes incompatible API changes. However, do developers really do follow that? Some may want to up their version because they added a major feature, but it doesn’t necessary mean that they made incompatible API changes. My first instinct is to look for release notes. Generally I find some, but there are cases where I don’t and it leaves me perplexed. If I upgrade, is it going to break all my software? By having proper release notes, this type of question can be easily answered.
The software I am using may be critical to my team and/or business, and as such, I may need a plan to smoothly upgrade. However, to write such plan, I may want to know what has changed to determine the upgrade priority.
Documentation is important when you have a user base. Here is my take on release notes.
Your release notes should not be long
Try to provide a light summary. When you communicate your changes, you want your users to understand quickly what has changed to give them a good and quick idea if the changes are important to them or not. If you believe your summary is too long, provide a link to discuss in details what has changed.
I’ve taken as an example the release notes of IdentityServer4 on GitHub. You can see the summary is quick yet to the point. A user looking to upgrade can easily filter through the notes and establish if some points are, to his eyes, critical.
Separate/group your points
Most people looking at release notes will glance at them. When you separate into sections it really sets the focus on what your users are looking to know.
Major or critical points
When you do changes that may affect the stability of your software in your clients environment, you should make sure your clients are aware of such changes. Provide them with a guide, if necessary, to help them ease their migration process.
If your update is a major change, if it is possible (depending of the software style), provide your users with a proxy/adapter to easy up the migration. Warn them of deprecated methods, but use that proxy to redirect the calls to your current API. This will ease up the change and will make it possible for old users to use your new library and slowly perform the migration while new users can start using your library with ease.
Bug fixes
Order your bug fixes in order of importance to you. People always start from the top when they read and if there’s a lot of notes, they quickly skim through. They thus may miss some bug fixes that in your opinion may not be critical but may have a significant importance.
Improvements
Release notes are also a way to communicate new and exciting features to your customer base. It is a way for the users to know that a new feature now exists and he/she may want to use it. It is also a way for new users to get a feeling of your progress and what type of improvements you do. They can thus use this section to justify the use of your software within their organisation using as argument the development of new features you are providing. It also shows that the software is evolving and still getting traction. Nobody wants to invest implementing or use a product that doesn’t get new and exciting features every now and then. It could definitely be a selling point, so you definitely should use it.
Communicate your notes
If you are able to do so, communicate your notes to your customer base. They should be available on your website and be easily accessible. Digging through a website to find the notes can be irritating for some users. If you have access to your customer base through email, you should also communicate them through that channel as well. If sending out emails is impossible, try to use the social networks to let the world know you have a new version out and provide them a link to your website. People will appreciate to know that you have a new release out there and that you are evolving your software.
Show all the fixes from the user’s version to the stable version (added 2017-03-01)
An interesting feature, that I saw implemented, is to have on your website a page that allows one to enter his current software version and the results is the list of all the fixes from his version up to the current stable version. This allows the user to proactively track what has changed from his version to the next. By applying some of the guidelines above you can easily show your major/critical points and your bug fixes
To conclude
Releases notes key for a software/application. You know that code is something that lives. Not only does it help a user with their upgrade decisions but it also reveals a few other things. One thing that it can reveal is how thorough you are with the way you deal with your application, and this includes but not limited to your code. It can also reveal if you are listening to your customer base by improving your software based on their feedback. Those may not feel like critical points to you, but they can definitely be for someone evaluating your product.
