Jan Krutisch, Co-Founder at Depfu

Here at Depfu, we have a pet peeve we mention every time we talk about our product but haven’t talked about a lot on this blog: Changelogs. Let’s change that - with a changeblog.

Sorry.

Changelogs are, in our eyes, an essential part of the documentation of an open source project, especially for libraries or packages or modules or whatever your language of choice calls these managed dependencies.

For me, a changelog serves at least three different purposes: It shows me breaking changes where I need to act when upgrading, it shows me new features and changes I could use and it gives me a good look into the governance of the project. Let’s look at each of them:

The most important question you want to answer with a changelog, especially in the context of upgrading a dependency: Should I expect API breakage, and if so, where?

Yeah, about that Semantic Versioning thing

Theoretically, you can answer the first part of that question by comparing the old and the new version number, but not every project out there follows Semantic Versioning and not every project 100% follows their own guidelines. Open Source is humans, and humans are messy sometimes. On the other hand, an incremented major version number does not necessarily break your code. Maybe you’re not using the part of the library where the API changed. Or you’ve heeded the deprecation warnings that were introduced a while back and are already prepared.

In contrast, a well written changelog should provide the necessary details to understand if you need to adapt your own code when updating this dependency at first glance.

Here’s a good example, clearly showing a breaking change and also explaining what you need to do to adapt (taken from the sidekiq 5.0.0 entry):

  • BREAKING CHANGE Job dispatch was refactored for safer integration with Rails 5. The Logging and RetryJobs server middleware were removed and functionality integrated directly into Sidekiq::Processor. These aren’t commonly used public APIs so this shouldn’t impact most users.

    Sidekiq::Middleware::Server::RetryJobs -> Sidekiq::JobRetry Sidekiq::Middleware::Server::Logging -> Sidekiq::JobLogger

Any other impacts?

But even if the upgrade would not break API compatibility, a changelog provides meaningful information. This includes things like upcoming deprecations (see above), new features (maybe something you’ve been waiting for for some time and now you can simplify your own code?) and of course, fixed bugs (where you might be able to remove a workaround or patch from your own code).

A good example would be (taken from the raven-ruby changelog, 1.0.0 release):

OTHER CHANGES:

  • Improved performance [zanker]
  • Deprecated config.catch_debugged_exceptions, replaced with config.rails_report_rescued_exceptions. catch_debugged_exceptions will be removed in 1.1. [nateberkopec, #483]
  • Added config.transport_failure_callback. Provide a lambda or proc to this config setting, which will be called when Sentry returns a 4xx/5xx response. [nateberkopec, #484]
  • JRuby builds fixed [RobinDaugherty]
  • Fix problems with duplicate exceptions and Exception.cause [dcramer, #490]
  • Added Exception Context. Any Exception class can define a raven_context instance variable, which will be merged into any Event’s context which contains this exception. [nateberkopec, #491]
  • Documentation from shaneog, squirly, dcramer, ehfeng, nateberkopec.

A changelog is like a CV

And then there’s the “read between the lines” stuff. This is probably less important during an upgrade, but can be quite helpful when choosing to use a library in the first place.

A good changelog gives you a detailed view into the development process. You can see how many bugs appear during development. You can see how often the project releases new versions. You can also get a feeling for the communication efforts of the team/ author behind the project. Sometimes even a bit of humour may shine through and shows you that a project is run by actual people with a soul and a heart.

At least that’s the theory…

If you’ve read this and you think “this all makes good sense”, then this makes me quite happy, but I also have some bad news for you:

Of the ~8000 npm packages and Rubygems that Depfu is currently tracking, we can only find changelogs (or GitHub releases) for roughly 60% of them. That’s not great, even if some of them may be those npm-isArray-5-lines-of-code modules where a changelog may be overkill.

Let’s change that.

This post is the first of a series on changelogs we plan to publish over the coming weeks. This time, I’ve tried to explain why changelogs are important. In the next post, we’re going to focus a bit more on the details of what makes a proper changelog. We’ll also talk about how to maintain a changelog and what tools might be available to make lives easier for overworked open source maintainers. Follow us on Twitter if you want to get notified.