Please publish changelogs

Signs of changes in a log.

When you release a new version of your library, please do a favor to your users and publish a changelog entry highlighting the most important changes.

The changelog tells your users what’s new – it gives them a reason to upgrade. It tells them what’s broken, so they won’t be surprised when nothing works anymore.

I’ve heard this quip that the changelog is one of the most important pieces of documentation, because even if the other documentation is lacking, it tells you what is outdated about the knowledge you have discovered yourself.

Sure, the commit history is always there, but usually it’s hard to understand. It’s easier to write a passable changelog than to curate the history.


How to do it in practice? keep a changelog has elaborate instructions. If you want to follow them, that’s great, but as long as you use a consistent format with version numbers and release dates, I’m happy.


About the author: My name is Miikka Koskinen. I'm an experienced software engineer and consultant focused on solving problems in storing data in cloud: ingesting the data, storing it efficiently, scaling the processing, and optimizing the costs.

Could you use help with that? Get in touch at miikka@jacksnipe.fi.

Want to get these articles to your inbox? Subscribe to the newsletter: