The Changelog-Versioning Revolution

At Batteries911, the BE team has the responsibility of maintaining an API that is consumed by 3 (soon 4) different clients: two iOS applications and a SPA. This means that, whenever we introduce a change, we need to be absolutely sure that the change is either non-disruptive or, if it is, that it was communicated properly and coordinated with all the FE teams.

(Not) Everything Needs a Version Number

Let me start with an important point: not all software needs versioning, or a changelog. If you’re building an MVP, versioning is probably not for you. If you work on a traditional full-stack website, then it’s very likely you don’t need versioning either.

  • Private and public APIs: whether you’re building a private (as is the case with B911) or public API, the teams leveraging your software will want to be informed of what changed and how, so that they can update their implementation accordingly. A good versioning practice and a detailed changelog will go a long way towards securing your success as a team and reducing — if not eliminating — “But I thought…” remarks.
  • Enterprise software: enterprise clients want to have complete oversight of the development process — versioning is one of the tools that can be employed to achieve this. It provides transparency and — when used properly — greater stability.
  • Established SaaS products: lately, I see more and more SaaS companies presenting a changelog to their users. These are a bit different from the changelogs you are used to seeing on GitHub — they are usually in the form of a blog post, newsletter or Headway widget. This is a nice way to keep your customers engaged and informed. It also lets them know that you care about them and are always working on things they love, so it’s worth to give it a try.

An Effortless Versioning Process

The versioning process that we came up with is dead-simple. The trick was to make sure that it was impossible not to follow the process, so that people were forced to adopt it and it became part of their workflow. For instance, here’s what we did at Batteries911 for the initial setup:

  1. We created a changelog: we used Keep a Changelog as a format. We created a first entry for our current version and started from there.
  2. We set up a PR template: GitHub has this nice thing called pull request templates, which are Markdown files that will be used to prefill the description field of new PRs. To make sure that people wouldn’t forget to record their PR in the changelog, our template contains a checklist. In order for the PR to be merge-able, all tasks in the checklist must be completed. Example tasks are “I have updated the tests”, “I have updated the API docs” and, of course “I have created a changelog entry.”
  3. We exposed the version number. One cool trick that we did was setting the current version number in a constant in our config/application.rb and including it in the HTTP headers of every response. This way, clients can ensure that they are using the correct API version (in case you maintain multiple versions at once, or want to raise an alert when a client should be updated, because it only supports an older API version).

The Changelog-Versioning Relationship

At this point, you might be wondering why I speak of versioning and the practice of keeping a changelog seem as if they were so intertwined. After all, you can record changes even without version numbers, and you can have version numbers without recording changes, right?

Source: xkcd.com

tl;dr

  • Keep a changelog. Even though you think it’s not for you, it probably is.
  • Establish a process that eliminates human error.
  • Keeping changelogs and tracking versions are intertwined: the former helps the latter immensely.
  • Changelogs are cool.

Technology leader and strategic advisor. I work at the intersection of people, software and words.