How to keep a good changelog

So you have decided to keep a changelog. 🎉
Now you might ask yourself what you need to do to make your changelog great.

The "keep a changelog"-ethos

Keep a changelog is a great resource on why and how you should keep a changelog. Although primarily targeted towards open source software, their principles can also be applied to product changelogs.

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.

Good news: Most of these principles are baked into Changes.

Which releases should be in your changelog

The basic rule is simple: a changelog should contain everything your users care about, like product updates, but not structural updates.

What should be included

  • Feature updates: "The dashboard now updates in real-time"
  • Updates in the background: "The web-app now loads 20% faster"
  • Bugfixes: "Posts would not update after pressing the save button"
  • Improvements in security: "We made our login system more secure" (Make sure to not include confidential information)
  • Deprecations and removals: "We deprecated the user-endpoints"

What should not be included

  • Code changes: "We refactored the posts controller"
  • Internal changes: "We switched from Mailchimp to intercom mail"
  • Company / Team changes: "We now have 5 new members on the billing team"

How to keep it human-friendly

Customers will not bother spending time on a changelog that is not easy and quick to read.

  • Keep it short (Make sure post are as short as possible, without losing detail)
  • Changelogs are not for long explanations (link to a blog post if necessary)

Related

Why keep a public changelog.

Why should you keep a public changelog.