Programming, philosophy, pedaling.

Towards an automated changelog workflow

Nov 5, 2020     Tags: programming, workflow    

This post is at least a year old.

I’m a very big fan of changelogs: I love being able to get a quick (human-readable) summary of what’s changed between releases, and I actively consume them when integrating libraries and tools into both my personal and my professional projects.

Despite that, I’m not very good at maintaining my own changelogs: I waver between forgetting to update them entirely and dumping a formatted version of my git log1 into them, defeating their entire purpose.

This post will hopefully collect some of my thoughts on changelog automation so that I can go about writing a tool (or composing preexisting tools) that solves changelog management for me. Maybe it’ll be useful to others too!

Brief background

This post is intended to be a collection of structured notes for myself, but it doesn’t hurt to provide some history and basic ground facts about changelogs for anybody else who decides to read it. So let’s do that.


First: changelog management is a burden that’s added to an engineer’s workflow. Like good commit messages, good changelog entries require active effort from maintainers and contributors. A good changelog management tool will need to reduce that burden to a manageable level.

Second: Because changelogs are burdensome, they need to require minimal buy-in from new contributors. Someone looking to contribute a one-line fix shouldn’t need to install a custom tool to ensure that the changelog reflects their work; that responsibility should lie with the maintainer(s).

Third: changelogs need to be human readable first, and weakly machine-consumable second. Why machine consumable at all? Because tools like Dependabot look for changelogs and make a best effort to include them their workflows. These workflows are fed to humans for consumption, so a good changelog tool will emit a format that allows existing automated tools to extract salient information for subsequent human consumption.

Fourth: changelogs are not immutable. Humans make mistakes (typos, forgetting changes, needing to yank a release, &c), and changelogs need to be updated to address those mistakes. A good changelog management tool will not be upset or cause additional work for users if a previous release entry changes beneath it2.

Prior art

A few different individuals and groups have made efforts to standardize and develop tooling around changelogs:

Goals and anti-goals

Given the observations and prior art above:

A data model for changelogs

Here’s a reasonable data model for a changelog, based on (and more constrained than) keep a changelog’s informal specification:

A changelog is:

A Header section is:

A Release Entry is:

A Change Section is:

A Change Tag is one of “Added”, “Changed”, “Removed”, or “Fixed”.

A Change is:

Next steps

Now that I’ve laid everything out above, I’m less sure that I need a brand new tool to manage changelogs for my projects. Instead, I think I need to:

If that doesn’t work out, you’ll probably be seeing a changelog management tool from me in the near future.

  1. Which I’d like to think isn’t bad, mind you. Just not appropriate, content- and detail-wise, for a changelog. 

  2. Even more concretely: a good changelog tool shouldn’t attempt to re-parse an already emitted changelog beyond the bare minimum needed to situate the new change entry. 

  3. I currently use my own style, which I like but certainly isn’t standard. 

Discussions: Reddit