Why you can't auto-generate your Changelog
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.
A good Changelog entry has…
A good Changelog entry has three primary aspects
- It’s at the right level of abstraction. Consumers of your product don’t care what files you tweaked or how. They care about the fixes and changes you’ve made that may impact them.
- It needs to be knowledge that’s useful to the consumer of your product. It’s a simple judgement call, but it’s one that has to be made.
- It needs to be written in a way that people who either aren’t geeks, or at least aren’t intimately familiar with your codebase can understand.
Changelogs from commits
Commits are at the wrong level of abstraction
A git log is filled with commits like: “ensured current_and_future_campaigns returns a relation”, or “cleaned up whitespace in User.rb”, or “fixed expected aspect name in update test for locations_controller_spec” These are useful to other developers on the project, but they aren’t things that are useful to the users of your product.
In short, they contain too much detail, at the wrong level of abstraction.
Commits are messages from one developer on a team to another one
They’re not messages to your users, and they shouldn’t be.
Commits frequently use jargon, and references to specific elements of code. This is absolutely fine, but it’s probably meaningless or useless to most of your consumers.
There’s no point
If I wanted a geek level listing of all the changes in your git history I could just ask git: git log --oneline Plus, git will let me slice and dice that information sixteen ways from Sunday.
You can’t edit them
As Commits From Last Night proves. Commit messages frequently aren’t written in a customer friendly way. Even if you’ve got very polite developers, everyone makes typos. You can’t edit the old commit. If you want a changelog that looks professional you’re going to have to manually edit it, the same mistakes every single time you generate it.
Tickets are at the right level of abstraction
…but they rarely have titles that are appropriate for a changelog.
How about “Item Finder - Page gets wonky after searching for content that doesn’t exist - plus 404”, or “Something’s eating up all the ram and taking down the servers” Not really appropriate for your changelog.
If you’re really following agile an agile methodology you have user stories that look like “As a
Some projects do take the time to curate their ticket titles. The results are almost usable as changelog entries too, but there are always exceptions. They’re generally worded well for the people who need to work on them, but not your consumers.
It’s a matter of human judgement
You want a changelog with the information that is useful to your consumers, and written at the right level of abstraction. This means people need to ask themselves some questions. “Do we need a changelog entry for this?”, and if so, “How do I summarize this change in a way that’s useful to our users?”
The first question sometimes eliminates information, through curation. That’s something tools can’t do. The second question changes the form of the information conveyed. It was directed internally, now it’s directed externally.
Want an easy tool to help manage this?
Check out changelog_manager. It’s a free and open source tool to help you easily generate high quality Changelog entries.