For as long as I’ve been programming I’ve always loved changelogs. I loved to read them, but writing them was always more of a burden. Why do I have this fascination?

The Purpose of Changelogs

Wikipedia has a predictably dry definition of a Changelog. There are a few different purposes for a changelog in my opinion. In no particular order:

• Keeping users informed of important features, fixes and changes
• (subset of above) Giving users a way to find a change that might (or did) affect them
• Giving potential users an indication of the health of the project or product
• Providing attribution and recognition to contributors
• Celebrating the accomplishments of the project or product.

Informed And Aware

One of the most important uses of a changelog is to keep the user base aware of what’s going on. Those bugfixes may have a serious effect on your users. That feature you finally shipped is likely to cause some cheering. The changelog is the medium by which we conduct that info. Maybe there are blog posts or tweets too, but we linkt to the changelog.

Health and Happiness

A vibrant changelog with a nice mix of entries — you do use Kano modeling for your project right? — is a great way to make potential users comfortable. Seeing a frequent with mix of improvements and features combined with not-too-many breaking and security changes is a sure way to put folks at ease.

Recognition and Celebration

The recognition of being attributed in a changelog is a huge boon to many developers. Having your name mentioned there is a high that is hard to explain. I clearly remember aspiring to be mentioned in the Changelogs of big OSS projects. I’ve been lucky enough to have that happen in the linux kernel and a few other places. It’s a pretty great feeling.

Also, looking back over the work you have accomplished can be really powerful.

Level Up Your Changelog

You should check out Keep A Changelog. It’s got great advice. If you want to automate some of that and give your users a great experience without a lot of fuss, check out Done Did. A friend and I made it and we’re trying to capture all the great things above and make Changelogs even more awesome. We hope to do this by making them less work, more interactive and more findable. I hope you’ll check it out!