Changelog From Conventional Commits: Git-Cliff
fhoekstra.eu
The changelog in platform engineering At my current job, we maintain a package that is used by developers in their own codebases to use a database service on the platform. Like any package or artifact that is released to then be used by application developers, this requires a clear release with a semantic version that communicates what users can expect from it: Does it contain only fixes (patch), or are there new features in the release (minor)? Most importantly, do users (potentially) need to change how they use the package when upgrading (major)?

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.

  • silverpill@mitra.social
    4·
    15 hours ago

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

  • FizzyOrange@programming.dev
    9·
    18 hours ago

    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.devEnglish
    2·
    14 hours ago

    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.

  • MajorHavoc@programming.dev
    5·
    19 hours ago

    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.nlOP
      4·
      13 hours ago

      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.