How to keep a great changelog

Although primarily aimed at open source software, Keep A Changelog has an awesome list of guiding principles to keep a good changelog, most of which apply to product changelogs too:

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

Note: we baked all of these into Changefeed, so you are keeping a good changelog out of the box.

Even though all of these are important, what makes a great changelog is what it includes and, just as vital, what it excludes.

What Should Go In The Changelog?

As the first priciple states, changelogs are for humans. Specifically, your changelog is for your users, so it should contain all the changes that could affect some of them. Corollary, it should not contain anything that will not affect any of them.

Let's look at some examples:

• New features, e.g. “added support for scheduling posts”
• Bug fixes, e.g. “disabled the invite button for free users”
• Deprecations, e.g. “removed support for old iOS versions”
• Security improvements, e.g. “closed a potential vulnerability”
• Invisible changes, e.g. “improved start performance”
• Credit to team members, e.g. “Jane fixed the cloning tool”
• Internal changes, e.g. “changed team structure”
• Technical changes, e.g. “refactored Billing module”

If you are unsure if a change will affect any of your users, err on the side of including it. As long as your individual entries are concise, they are easy to filter visually.

How To Write Good Changelog Entries

After years of keeping changelogs, we also have some best practices for writing the individual entries:

• Keep entries concise (ideally below 100 characters)
• Link to a blog post if you need to elaborate
• Use imperative mood
• Capitalize the subject line
• Use past tense if your users are upgraded automatically
• Use present tense if your users upgrade manually

Ready to kick off your changelog? Get started with Changefeed and publish your first release in seconds!