ApiVer – a versioning policy for libraries
Paweł Polewicz (~ppolewicz) |
ApiVer is an evolution of SemVer 2.0.0 – the well-known and well-designed standard which ends up leaving some challenges that hamper productivity in the long term. This talk will explain why it is worth it to acquaint yourself with ApiVer and how you can use it to reduce maintenance overhead and improve the experience of your library’s users.
ApiVer allows non-backward compatible changes to signatures such as the addition of mandatory function parameters and deleting methods from public interfaces without breaking the functionality of the software that uses a library upon upgrade. It also ensures that minor bugfixes and performance optimizations of old functions remain available to everyone without the need to backport anything to the old branches.
It is not easy for the library maintainer, and it does add a little bit of overhead to the development cycle, but it is a better choice for the library user than just SemVer.
Let's take a look at the typical challenges that a project may face:
- If the API changes in an incompatible way, the major version of SemVer needs to increase.
- If the major version is increased frequently, many major versions need to be supported. Bug fixes need to be backported, and multiple patch releases need to be managed on many branches.
- The users are encouraged to pin their dependency to the major version that they started with, so they cannot access new features and optimizations.
- As the cost of supporting a high number of versions increases, library developers are faced with an impossible choice: productivity or an elegant API interface?
There are a few possible choices to be made here:
- bite the bullet: update the signature, increment major SemVer, and put an "upgrade wall" between the current users and the new feature, and any future performance optimizations;
- default to legacy style forever, compromising the elegant API design;
- default to "legacy" style for now and change the default to "modern" in the next major SemVer release (although in this case, performance optimizations still get cut off, just a little bit later).
I faced this dilemma myself a couple of years ago, and, as it turns out, there is one more possible choice. It is quite intuitive if a specific condition is met: the library maintainer also maintains at least two applications using this library.
During the talk, we will go through both the problem and the solution, using a real-life example.
What you will learn from this talk can be directly applied to library code with little effort, allowing the developer to continuously improve APIs with no need to increase the major SemVer version.
- Various kinds of maintenance waste - 12min
- Hidden waste on the client side - 2min
- Seemingly impossible tradeoff - 3min
- ApiVer solution description - 5min
- How it works in practice - 8min
Familiarity with SemVer
Pawel is a software engineer with 18 years of professional experience ranging from programming for a local startup to leading large teams for an international corporation. Initially focused on doing things right, later, he switched to doing the right things. Four years ago, he resigned from a full-time position and founded a software house that has now completed over 120 projects for businesses of all sizes based in the USA, Canada, and the UK, from toilet paper level tracker to fintech time series analyzers.