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)
Why keep a public changelog.
Why should you keep a public changelog.