Dave Farley’s post on CI and the Change Log popped up on my Twitter today, and I put this together as it touches on things I’ve been thinking about recently.
In this post when I write changelog, I mean version-control log rather than e.g. a CHANGELOG.md
Structured Changelogs vs Unstructured
I’ve recently come to see the virtue of having a well-defined structure for changelog entries.
Projects like Angular, Karma, and others have adopted a specific form of semantic commit messages that sit in that rare sweet spot of both machine-parseable and human-readable.
A typical commit will look like this:
feat(hash-support): Support Hashes from Secrets Manager
* This is to simplifies the number and namespace of the secrets stored in secrets manager
* It allows us to update a set of interdependent creds like AWS keypairs at the same time - avoids race conditions causing invalid credentials combinations
The header in this example contains, broadly, the type of work, the scope of the change, and a short description.
There is work in progress to standardise across the slightly divergent interpretations of what has become a pseudo-standard in predominantly the Javascript community (as a result of major players adopting this style) - the Conventional Commits project is spearheading this standardisation.
Why structure your commits?
In the above blogpost, Dave Farley writes
Instead of thinking of the change-log as a linear record, think of it as part of the “historical search-space” of information, linked by keys (like the id of your story and the id of your release candidates)
Structured commits are another step in the direction of unlocking the value tied up in an accumulated dataset - the VCS log.
Machine-parseable into data
If you’ve ever had a debate like “I think we’re doing too much refactoring” “No, we’re not”, well-structured commits give a route into resolving this. An ingestible format unlocks a new dimension alongside stories and velocity to talk about the nature and volume of work that is happening.
A vocabulary for describing work
Having a way to describe a thing necessarily changes the way you are able to perceive and think about a thing. Adding structure to the description of work will change the way you think about work.
As an example, my team have adopted the Conventional Commits specification - we now have a tool to describe the difference between a refactoring and a fix, and crucially separate the two in the story of our codebase.
Standards lower barrier to entry
We rotate developers between teams and cross-team pair/mob a fair amount at Unruly. Being able to go from one team to another and not have to learn a new way of reading code history is one fewer thing preventing us doing this more frequently.
A language for asking questions
Continuous Integration, and by extension Continuous Delivery, emphasises small commits which are integrated often. As with all datasets, size drives a need to have a better way of interrogating the data than having to read every entry.
It empowers us to ask questions like “How often are we having to fix this part of the codebase?” and “Are there types of work that introduce regressions more often than others?”
If your team or company practices CI and commit-small-and-often, take a look at structuring your commits and see what you can learn from it.