Changelogs are an invaluable, and often neglected part of any software project. So, how do you do that?

A good changelog helps you users to understand:

• Why they should care about your latest version
• If any of your changes affect the problems or frustrations they’ve been having.
• If there are any changes that might affect how they use your app / library.
• Why your efforts are worth their continued support.

A great changelog does all that, and shows the personality of your team.

Let’s start by taking it as a given that a Changelog file is something very valuable that every product should come with. Even if your “product” is a library for other developers.

With that in mind, the question rises of “How can I make it really easy to generate one”. Many developers have had exactly that thought. There are many free and some paid solutions that will “Autogenerate your changelog from your git commits/tickets”. The simple fact is, that no matter how well they’re written, you shouldn’t use any of them.

First, it should be noted that not all stories are “User Stories”. For example a developer might be tasked with manually running some script. The Story might simply be “run the fooberry script”.

For everything that effects the UI, use a template:

As a < type of user >
I want < to perform some task >
So that < I can achieve some goal >

Note that it’s all about what the user wants. This isn’t about instructing what change to make to a system. It’s about advising implementers on what the desires of the user are.