When publishing a package for use by programmers, automated changelog generation is very beneficial. In this blog post, I explore how to do it in a simple way that works everywhere.
I’m a big fan of keepachangelog. The only automation I recommend is that this is read from tag to tag and used as nice releases. But a human writing the changelog directly in the “Unreleased” section will always produce the most useful changelog.
What would really bring the state of the art forward would be automated checks whether a given interface change is really fully backwards-compatible or not. But this would need to catch changes such as
- changed behaviour
- removed functions, methods, enumeration values, …
- added exception types or error codes in return values, leading to looser post-conditions (client code needs to check for additional errors)
- stricter pre-conditions
- in libraries, upgrade to dependencies which include any breaking changes (because they can now conflict with other dependencies in a formerly working client project, and break these).
(Edit: There is a brilliant YouTube video by a guy called Rich Hickey, with the title “Spec- ulation”, which talks about these foot-guns. Hickey is designer of Clojure, a Lisp dialect for the JVM, but his observations are independent of languages - it is all about APIs).
That is indeed a difficult problem. Integration testing and contract testing can help to avoid this, but one can never be 100% sure.
It is the whole topic of Rich Hickeys talk linked above that breaking an API is a choice. And it is not a solution to not define an API and not agree any contract at all.
IMO automated changelogs like these are not especially useful. Better than no changelog I guess, but nowhere near as good as a proper changelog. But proper changelogs take actual effort.
@fhoekstra Such tools are worse than useless. Every time I see an automated changelog it’s mix of dependabot commits, “fix CI” and other meaningless messages.
Not having a changelog is better, because then you just go straight to a commit history and don’t waste your time trying to parse machine-generated slop.
Oh, nice.
I’m always looking for another ChangeLog tool.
That said, I never leave my ChamgeLogs up to automation.
My git logs are open to my users for full details, but my ChangeLogs are how I communicate which changes my users probably need to be aware of.
So far, this hasn’t yielded well to automation. But my team is still considering standardizing our commit log messages enough to allow it someday.
Thanks for your feedback!
Some thoughts:
- You could configure your
cliff.toml(generated withgit-cliff --init) to ignore any commits that aren’t interesting to your users - You could use “squash merge” to the prerelease/staging/development branch so that you can commit without worry, and then only have your PR titles follow conventional commits (if the change is interesting to your users)
I should probably add those to the blog.
But yeah, I get preferring to write manual tailored changelogs. Personally I am just a little neurotic about single source of truth and a huge Git nerd. And I know that at least in this job, my users are neurotic enough to prefer completeness.
We do always squash merge, which certainly helps.
I was not aware of
cliff.toml. Thank you!
- You could configure your
At work, I set up convco for automated commit checks and changelog generation with custom/slightly adjusted configuration of conventional commits (types) and changelog template.
Nice, I hadn’t heard of that one yet!
