Your changelog should be based on your user-stories!

This article is, more or less, a follow-up to “Your git log is not a changelog!”, published by @aureliengateau a few days ago.

Aurélien says an application’s changelog should not be generated from its commit history. And that commits should not be squashed in order to produce a changelog. And I agree 100% with these ideas!

For me, the changelog of your application should be built from your User Stories. Not from your Git history.

Indeed, as their name indicates, User Stories are oriented towards… Users!

They exist to describe evolutions and improvements, which will benefit people using the application. And they are usually written by someone close to the users, who knows their needs and their language. Maybe a product owner, maybe someone from your business or sales team, maybe a developer who does more than only write code.

They are, therefore, perfect as a basis for the changelog—aimed for these same users!
The finished User Stories at the time of a release correspond to the changes, intended for users, delivered in that release.

In contrast, the Git commit history is a set of technical information.
Developers write it. With their own language. And they think about their future selves: people who will read this history to understand how something was implemented and why it was done this way.

You might wonder: “what about technical tasks?”

Well, what do these bring to users?
If you can answer this question, you know what to write in the changelog ;-)

But I think that purely technical tasks don’t necessarily have to be in the application’s public changelog.
Typically, “We reworked the code” without changing any functionality… The user doesn’t care and doesn’t need to know!

That said, remember fixing a bug is not a technical task: you do it to solve a problem users are suffering from. This fix is requested and described in a User Story. And, so, it will be in the changelog.

Also, “what about technical projects, like a library or an API?”

Developers who will integrate this library or who will consume your API are your users. Again, evolutions should be described in User Stories.

I’ll admit, if you maintain such a project on your own time, OK, maybe you can’t spend your time writing User Stories…
Still, perhaps issues, reported by your users, could play that role? Or pull-requests¹?

In all cases, changes made to an application aim to meet expectations of its users. These expectations are materialized in User Stories.
Therefore, the changelog should be generated from these User Stories.

Illustration by Thomas Bormans on Unsplash