Automated changelog generation (fhoekstra.eu)
from fhoekstra@feddit.nl to programming@programming.dev on 08 Nov 12:01
https://feddit.nl/post/45839000

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.

#programming

threaded - newest

MajorHavoc@programming.dev on 08 Nov 13:44 next collapse

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.

fhoekstra@feddit.nl on 08 Nov 14:22 collapse

Thanks for your feedback!

Some thoughts:

  • You could configure your cliff.toml (generated with git-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.

MajorHavoc@programming.dev on 08 Nov 19:17 collapse

We do always squash merge, which certainly helps.

I was not aware of cliff.toml. Thank you!

FizzyOrange@programming.dev on 08 Nov 14:28 next collapse

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.

Kissaki@programming.dev on 08 Nov 18:32 next collapse

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.

fhoekstra@feddit.nl on 08 Nov 18:51 collapse

Nice, I hadn’t heard of that one yet!

HaraldvonBlauzahn@feddit.org on 09 Nov 10:25 next collapse

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).

fhoekstra@feddit.nl on 09 Nov 16:40 collapse

That is indeed a difficult problem. Integration testing and contract testing can help to avoid this, but one can never be 100% sure.

xkcd.com/1172/

HaraldvonBlauzahn@feddit.org on 09 Nov 18:08 collapse

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.

theherk@lemmy.world on 09 Nov 11:30 collapse

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.