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.

  • HaraldvonBlauzahn@feddit.org
    3·
    15 hours ago

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

      • HaraldvonBlauzahn@feddit.org
        1·
        8 hours ago

        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.