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.
this post was submitted on 08 Nov 2025
17 points (90.5% liked)
Programming
23417 readers
235 users here now
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
- Follow the programming.dev instance rules
- Keep content related to programming in some way
- If you're posting long videos try to add in some form of tldr for those who don't want to watch videos
Wormhole
Follow the wormhole through a path of communities !webdev@programming.dev
founded 2 years ago
MODERATORS
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!
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!