Keeping a great Changelog

Changelogs are an invaluable, and often neglected part of any software project. So, how do you do that?

A good changelog helps you users to understand:

  • Why they should care about your latest version
  • If any of your changes affect the problems or frustrations they’ve been having.
  • If there are any changes that might affect how they use your app / library.
  • Why your efforts are worth their continued support.

A great changelog does all that, and shows the personality of your team.

Shifty Jelly’s Pocket Casts is notorious for their fun, and informative changelog entries:

  • Equal Opportunity variable speed playback. Why should MP3s have all the fun? Welcome AAC & OGG! * Bzzz. Bzzz. You can now choose which podcasts to be notified of.

Slack’s been doing a pretty bang-up job too:

  • Fixed: The app now automatically scrolls down when you begin writing a file comment, giving your precious fingertips much needed beauty rest. * Fixed: Time zones were sometimes shown with incorrect deltas. Now your coworker who is 5 hours ahead of you will no longer simultaneously be 8 hours behind you.

I can’t overstate how valuable it is to have a Changelog with personality. As soon as you see that one of the apps you use has a great changelog you look out for them, and always stay on top of what they’ve fixed and added. Then you start spreading the word, because not only did they add good stuff, or fix that really annoying bug, they made you smile along the way.

A Changelog with personality helps build evangelism for the thing you’ve spent so much time building.

The guts of a good Changelog Entry

  1. It must speak in terms users understand. Most of them won’t be intimately familiar with your source code. Don’t use internal jargon. If a bug is fixed, speak in terms of the actions that caused it, or the behavior it exhibited, but not the specific classes, unless you absolutely have to.
  2. It must be knowledge that’s useful to your users. Speak to the features and flaws that affect your customers. Users don’t care that you refactored some unit test, or reformatted your comments.
  3. It has to be at the right level of abstraction. Even if your writing an open source library. The Slack timezone bug above was handled perfectly. They could have mentioned which class & method had the bug, or the conceptual flaw that caused the bug, but that’s all too fine grained for a Changelog. Instead, they spoke at a higher level of abstraction.

Changes need to be grouped by type

Group your bug fixes. Group your features. Group “all the things!”

Imagine a user who’s been particularly frustrated by a bug in your app. They’re going to open your changelog and immediately try and find out if you’ve fixed it in this release. Help them. Don’t frustrate them further by making them hunt for it in a jumble of features, fixes, and changes.

Dates are important

Versioning your software is great, but dates are important too. When did version 6.0.0 come out? Did I have that problem before then or after?

Additionally, not everyone in the world keeps dates in the same format. 06-08-16. Is that August 6th or June 8th? It depends on who’s reading it. Year Month Day is the only one that makes any logical sense no matter where you are. XKCD even had a Public Service Announcement about it.

To summarize

  • Write at a high level of abstraction
  • Speak to things that affect users, not developers.
  • Group things so that people can find them easily.
  • Add some personality.

Want an easy tool to help manage this?

Check out changelog_manager. It’s a free and open source tool to help you easily generate high quality Changelog entries.