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.

Comments or questions? Send me an e-mail.