Now I find myself designing event schemas for sending messages across a distributed system. It's a very similar problem with similar pain points and solutions. Adhering to data contracts is critical to ensure we don't frustrate event subscribers or bring down systems.

Versioning APIs is translatable to versioning event schemas, but if you can effectively evolve schemas, you don't actually need versioning. Effective evolution of schemas comes down to avoiding breaking changes.

Though I covered that briefly in the article above, here I want to thoroughly address breaking changes and propose more solutions to avoiding them.

What are Breaking Changes?

Essentially, a breaking change to a schema (in an API or event context) is anything that requires a consumer to make an update on their end. It's a change that forces change. Schemas will evolve, but once a schema is in use in production, you have to be very careful not to break the data contract.

Removing an event format or changing an event's basic structure constitutes a breaking change. But the nuts and bolts are at the attribute (the field or property) level.

Structural breaking changes

Here's a list of structural breaking changes for schema attributes:

• Renaming Attributes – Changes to an attribute's name, even if it's just changing the case (for example, from camelCase to TitleCase), is a breaking change.
• Removing Attributes – Taking an attribute out of a schema.
• Data Types Changes – Changing data types, even if the change seems compatible.
• Making Attributes Required – Anytime you mark an attribute (even a new one) as required when it wasn't before, it's a breaking change.

Semantic breaking changes

The other primary category of attribute-level breaking changes has to do with changes in what the data means, or semantic changes. They force consumers to re-interpret the data they're getting.

They are as follows:

• Format Changes – Any change to the format of an attribute.
• Meaning Changes – When the declared or implied meaning of data changes.
• Stricter Constraints – When attribute requirements are added or made more restrictive.

It's important to note that what counts as a "breaking change" might be more nuanced. Changing an amount from dollars to cents still forces a change by event subscribers, in interpreting the meaning of the data being sent. Be careful of those, as they are not always obvious.

What are Non-Breaking Changes?

We can generally describe non-breaking changes as additive or permissive ones. These are changes that don't require change for consumers.

Here is a list of non-breaking attribute changes:

• Adding New Attribute – In all schema contexts, the addition of a new attribute is a non-breaking change, so long as it's not required (for example, for a POST request).
• Making Attribute Not Required – When an attribute was required but newer schema versions do not require it.
• Looser Constraints – Things like more permissive integer ranges (min and max) or allowing for greater decimal precision. Be cautious and communicate with consumers, though, as they may rely on stricter constraints.

Non-breaking changes can often be avoided. But evolving schemas effectively can be challenging and require a lot of thought so as not to break schemas and consumers' trust.

How to Evolve Schemas

Sadly, the list of breaking changes is longer than the non-breaking ones. But there are some strategies for evolving schemas in a non-breaking way.

1. Domain Knowledge – Understanding the domain will help ensure you don't end up with poorly named attributes, attributes on the wrong object, or incorrect data types.
2. Specific Attribute Names – Rather than changing an attribute's name, data type, or format, introduce a new attribute with a more specific name and correct the data type or format.
3. Attribute Names With Intent – Leverage attribute names that reflect their format or intent. For example, consumers might not know whether providerCost would be in dollars or cents, so specify with providerCostInDollars or providerCostInCents. This will also prevent a breaking change if you're having calculation precision issues with dollars and decide to deliver the cost in cents.
4. Drafted Schemas & Attributes – Utilize "draft mode" extensively at the schema level, getting feedback on attributes in simulated environments before they are live in production. For schemas that are in use in production, you could introduce a draftedAttributes object and dump experimental (non-production ready) attributes into it. Communicate with consumers that they attributes are being refined – so they should expect breaking changes – and will be moved to the main schema when ready.
5. Support Existing Attributes – Leave old attributes in the schema. Don't remove old attributes unless you've been able to coordinate a deprecation/sunsetting strategy with consumers.
6. Versioning – If necessary, version your schemas. Although it can become quite difficult to maintain, versioning your schemas is a way to allow for backwards compatibility but move forward with a new schema. You can do high-level versioning (for example, v1 and v2) or more granular semantic versioning (for example, v1.0.1). It's best to version each schema independently, so you don't have to, for example, copy all API v1 endpoints to v2.

Conclusion

Breaking changes are a quick way to break trust for any API consumers or event subscribers. I hope that the guidelines above will provide more insight what constitutes a breaking versus non-breaking change, and how to evolve schemas effectively.

If you can't avoid breaking changes, make sure to coordinate with any and all consumers. You can actually earn more trust with your consumers if you effectively evolve schemas and communicate breaking changes when they are necessary.

Releasing modern software might seem daunting and complicated. In this article, I'll expand on the concepts involved in the process, from managing dependencies to building in the cloud.

Articles and tutorials usually cover a specific tool and dive right into it before laying down the foundational knowledge. In this article, I'll provide that foundation by introducing the concepts that go into these tools.

The topics I'll cover include dependency management (and what dependencies really are!), build systems, and continuous integration systems with a little bit of icing on the cake. Having this background will help set you up for what's to come.

What are Libraries?

Say you're chipping away dutifully at your tasks. You create a collection of utilities that make your job easier. You're then assigned to a different project in which you need the same utilities, and copy them over. Congratulations, you just created a library and used it across two projects! 😁

Libraries are collections of pre-written code that developers use to optimise tasks. They boost our productivity by abstracting away the boring and repetitive stuff. Numpy, Matplotlib, Lodash, jQuery, and React are all examples of popular, open-source libraries.

You've probably noticed that each of these libraries (or any other library) has a version number. It's usually constructed as a few numeric fields separated by periods: v1.0.0 or just 1.0.0. These numbers are not random! There are many schemes for defining a version of a product.

Some products use the build number generated by a compiler or CI/CD tool (we'll look into these in a minute). Other products use the date of the build instead of the build number. Others use a build hash.

The most prominent versioning scheme is called Semantic Versioning. It's what most (if not all) code libraries use.

What is Semantic Versioning (Semver)?

Semantic versioning is a versioning scheme in which you have 3 fields, each separated by a dot. For now, we'll call the first field (on the left side) Major, the one in the middle Minor, and the last one Patch. It looks exactly like this, with some derivations: Major.Minor.Patch.

Per the Semver standard, all fields must increment only. You can't decrement any of them. When a parent version is incremented, all children are reset. So incrementing Major resets Minor and Patch to 0.

The patch version

The Patch version is the most frequently changing number. When this number is incremented, it indicates a change that doesn't add new features or break existing functionality. These may be security fixes, performance optimisations, bug fixes, and so on.

Changes to the Patch version are always two-way compatible, as long as parent versions are the same. Code written on v1.0.1 will work on v1.0.0 and v1.0.2.

The minor version

The Minor version is the second most frequently changing number. A change to this number indicates a feature update that doesn't break existing functionality.

Changes to the Minor version are always forward compatible, as long as the Major version is the same.

Code written with v1.1.0 will work with v1.2.0 but may not work with v1.0.0, as you may be using features added in the more recent version.

The major version

The Major version is the highest priority and the most "dangerous" field of the three. When this number is incremented, it indicates breaking changes. These are usually API/interface changes and/or entity renaming and removal.

A new Major version is not meant to be compatible with any other Major version, so don't expect v1.0.0 to work with v2.0.0 or vice versa. Your code may compile after an upgrade, but that's just pure luck.

There are cases in which library authors break underlying logic without affecting the public API you use, so it doesn't break your code. But these are exceptions.

Python 2 and Python 3 are examples of breaking changes. Python 2 print statements don't work on the Python 3 interpreter, and vice versa. Some of it may work, like for loops and other basic structs, but that's about it.

It's recommended that you stay up to date as much as possible with the Patch version. If you need the new features, upgrade your Minor version. A change in Major indicates enormous changes. So be careful when you're upgrading.

There's usually a migration guide with each major release that you should follow. You can read more about Semver in the official documentation.

So... how do we install and use external libraries written by other people in the first place?

How to Manage Your Project's Dependencies

In the past, the best that we could do was to actually copy the source code of the libraries we were using into our projects. We applied changes to the library's code, fixed bugs before they were released, and had control over the code.

But this practice, commonly referred to as vendoring, has fallen out of favour for multiple reasons.

If you had applied changes and a new version was released, you had to re-apply all those changes again. It's a manual process that needs to happen every time you update or download a library. It's cumbersome, takes a lot of time, and may break extra functionality that you added.

This quickly gets out of hand when increasing the project's complexity and scale, which leaves us with the better option: Dependency Managers.

What is a Dependency Manager?

A dependency is a library or utility that your project needs to work. Simply put, if Program A requires Program B to compile and/or run, Program A is dependent on Program B. A program can depend on multiple other programs.

A dependency manager is a tool that automatically keeps track of a project's dependencies. It allows you to run simple commands in the terminal to install, update, and remove dependencies. NPM, Yarn, Composer, Gradle, and Bundler are all examples of dependency managers.

Don't confuse these with Package Managers, as those are tools that manage system-wide packages. apt-get, yum, Homebrew, and Chocolatey are package managers.

Some package managers can manage system-wide packages and project dependencies. NPM and Yarn are examples of this.

How does a dependency manager work?

A dependency manager uses two main files: a manifest and a lock file.

The manifest is a list of your project's direct dependencies. It lists the dependencies that you directly specified when installing something. So when you run npm install jsdom, it adds the jsdom package to the list of dependencies in the project's manifest.

But the manifest is not enough. A dependency may have dependencies, and those may have dependencies as well, and so on, forming a dependency graph. A manifest includes only direct dependencies.

Therefore, when you run npm install jsdom, the manifest will only list jsdom despite jsdom having other dependencies of its own. So, how do dependency managers keep track of the whole dependency graph?

What are Lock Files?

A lock file is a log that lists all the project's dependencies. This includes direct dependencies (listed in the manifest) and the whole dependency graph. It lists every dependency with a specific version, the repository it was fetched from, and other details.

This image shows a comparison between the dependency graph (listed in the lock file) and the direct dependency list (listed in the manifest) of jsdom, a JavaScript implementation of many web standards for testing.

Okay, we know the exact dependency graph, but so what? So everything! We often have multiple developers working on the same project. A dependency manager may install different versions of a library if multiple developers install the project's dependencies using only the manifest.

A lock file locks each dependency in the graph to a specific version, allowing us to have reproducible builds on different machines. This means that every time someone runs npm install, the code is guaranteed to work. This also makes it easier to report bugs by including a lock file in the report.

Lock files also allow dependency managers to reuse cached packages instead of downloading the latest version every time you build your project.

So we've learned what libraries, semantic versioning, and dependency managers are. Now it's time to build our project.

What are Build Systems?

Every build process is a build system in one way or another. A build system is a set of transformations that transform a source into an artifact. It may be a simple command that starts up a compiler, a script to generate pdf from text files, or even a GUI solution that builds your project and generates a binary.

A build system generally consists of 3 components:

• Targets
• Dependencies
• Rules

A target is the desired output. If you want a binary called "test.exe", then your target is just that. Dependencies are project dependencies and may include environment utilities like having the C++ compiler installed, npm available, and so on. Rules define how you go from source to target. They may also be the commands used.

A build system may be configured to test your app, generate coverage reports, and lint sources before building as part of its rules. But a build system is manual and local by default. You have to start it up yourself, and it only produces an output on your local machine.

So... what if you want multiple developers to be able to release versions of your app incrementally? This is where CI/CD comes in!

Continuous Integration Systems

In short, Continuous Integration (CI) is a paradigm in which you continuously validate changes to a product. A CI system automatically builds and tests every change to avoid problems that may arise when waiting for a release.

Continuous Delivery (CD) is the practice of automating the release process. Major releases are automatically deployed to staging and production, providing an automated release process.

Continuous Deployment (CD) is a step-up from Continuous Delivery. It's the practice of automatically deploying every change if it passes all stages of your production pipeline, without waiting for any explicit approval. This practice emphasizes test automation and user feedback, often leading to multiple software updates a month, week, or even a day!

It's a broad concept that you can read more about in this article. For now, we'll refer to the systems that host these practices collectively as Continuous Integration Systems.

A continuous integration system (CI for short) is a build system in the cloud that activates a project's build system on demand and automatically. It's a keystone in the success of agile teams.

CIs consist of three main components:

• Triggers
• Actions
• Recipes

Triggers are events that the CI listens for to start the build system. These events may be a commit on main branch, a pull request for feature previews, or one of many others. Each platform supports several events.

Actions are commands and scripts that are started upon triggers. You may say: "Build project upon commit on main branch" in the system's language.

Recipes are configurations that specify triggers and actions, environment setup, environment variables, build systems, and system dependencies. They're the system's language.

Note that you can have multiple build systems on the same CI, each with different targets and rules.

TravisCI, Jenkins, CircleCI, GitHub Actions, and GitLab CI/CD are examples of CIs we come across every day. The following is an example GitHub Actions recipe to release new versions of a program and send them to GitHub Releases:

on:
  push:
    branches:
      - main // will start the CI when a push to branch main is made

jobs:
  release_linux:
    runs-on: ubuntu-latest // must be run on ubuntu@latest

    steps:
      - name: check out git repository
        uses: actions/checkout@v1

      - name: install Node.js, npm and yarn // required env tools
        uses: actions/setup-node@v1

      - name: install deb packages // required env dependencies
        run: sudo apt-get install fakeroot dpkg rpm

      - name: build and release app
        uses: kl13nt/action-electron-forge@master
        with:
          // release to github releases after successful build
          release: ${{ startsWith(github.ref, 'refs/tags/v') }}

I've omitted a ton of config stuff in there, but you get the idea. I specified the trigger as a commit on "main" branch and the actions to clone the project's repository, install NodeJS, npm, yarn, and other environment dependencies.

The build stage will run an npm-scripts build system which will lint and test the code before building. The CI will then send the output binaries to the project's GitHub Releases page.

A lock file also comes into play when pushing to a CI as well! If the CI installs different versions of dependencies than the ones you have locally, it may fail. This is why a lock file is as necessary for CIs as it's for developers, so you can rest assured that the code that worked on your machine will work the same way on the CI.

Conclusion

If you've made it this far, I really hope this was an inspiring (and gentle!) learning experience. You can find more of my content on my website. Thanks for reading!

Further Reading

• What is Package Lock
• The Missing Semester of Your CS Education - Metaprogramming
• The Simple Magic of Package Manifests and Lockfiles

If you've been burned by API changes, you're probably the one fussing. If you are a maintainer of an API, you might also be fussing about trying to field challenging questions like these:

# Is this version 2 of just products or of the entire API?
/v2/products

# What catalyzed the change between v1 and v2? How are they different?
/v1/products
/v2/products

These questions around versioning are not easy to answer. It's not always clear as to what v1 or v2 is referring to. And we should not just make a second version of an endpoint when the first no longer seems to suffice.

There are clear reasons why your API needs to have versioning, and there are clear strategies for how to effectively navigate API changes.

However, I have found that most developers--including myself, until I learned some lessons the hard way--are not aware of these reasons and strategies.

This article seeks to highlight those reasons for versioning and strategies for accomplishing it. We're going to assume a REST API context, as it's a standard for many APIs, and focus on the versioning aspect.

What is Versioning?

We should start with level-setting on what is meant by the term "API versioning". Here's our working definition:

API versioning is the practice of transparently managing changes to your API.

Versioning is effective communication around changes to your API, so consumers know what to expect from it. You are delivering data to the public in some fashion and you need to communicate when you change the way that data is delivered.

What this boils down to, in the nitty gritty, is managing data contracts and breaking changes. The former is the primary building block of your API and the latter reveals why versioning is needed.

Data Contracts

An API is an Application Programming Interface, and an interface is a shared boundary to exchange information. The data contract is the heart of this interface.

A data contract is an agreement on the shape and general content of the request and/or response data.

To illustrate a data contract, here's a basic JSON response body:

{
  "data": [
    {
      "id": 1,
      "name": "Product 1"
    },
    {
      "id": 2,
      "name": "Product 2"
    }
  ]
}

It's an object with a data property that is an array (list) of products, each with an id and name property. But the data property could have just as easily been called body, and the id property on each product could have been a GUID instead of an integer. If a single product was being returned, data could be an object instead of an array.

These seemingly subtle changes would have made for a different agreement, a different contract, regarding the "shape" of the data. The data shape could apply to property names, data types, or even the expected format (JSON vs. XML).

Why is Versioning Needed?

With APIs, something as simple as changing a property name from productId to productID can break things for consumers. This very thing happened to our team last week.

Thankfully, we had tests to catch changes to the API contract. However, we shouldn't have needed those tests, because the maintainers of the API should have known this would be a breaking change.

Breaking Changes

This was a breaking change to the agreed upon data contract because their change forced us to change our application as well.

What constitutes a "breaking change" in an API endpoint? Any change to your API contract that forces the consumer to also make a change.

Breaking changes primarily fit into the following categories:

1. Changing the request/response format (e.g. from XML to JSON)
2. Changing a property name (e.g. from name to productName) or data type on a property (e.g. from an integer to a float)
3. Adding a required field on the request (e.g. a new required header or property in a request body)
4. Removing a property on the response (e.g. removing description from a product)

API Change Management

It is never wise or kind to force consumers of an API to make a change. If you must make a breaking change, that's what versioning is for, and we'll cover the most effective ways to version your application and endpoints.

But first let's briefly discuss how to avoid breaking changes in the first place. We could call this API change management.

Effective change management in the context of an API is summarized by the following principles:

• Continue support for existing properties/endpoints
• Add new properties/endpoints rather than changing existing ones
• Thoughtfully sunset obsolete properties/endpoints

Here's an example that demonstrates all three of these principles in the context of the response for requesting user data:

{
  "data": {
    "id": 1,
    "name": "Carlos Ray Norris",     // original property
    "firstName": "Carlos",           // new property
    "lastName": "Norris",            // new property
    "alias": "Chuck",                // obsolete property
    "aliases": ["Chuck", "Walker"]   // new property
  },
  "meta": {
    "fieldNotes": [
      {
        "field": "alias",
        "note": "Sunsetting on [future date]. Please use aliases."
      }
    ]
  }
}

In this example, name was an original property. The firstName and lastName fields are being implemented to provide a more granular option, in the event that the consumer wants to display "Mr. Norris" with some string interpolation but without having to parse the name field. However, the name property will be supported in an ongoing fashion.

alias, on the other hand, is going to be deprecated in favor of the aliases array--because Chuck has so many aliases--and there is a note in the response to indicate the sunsetting time frame.

How Do You Version an API?

These principles will take a long way in navigating changes to your API without needing to roll a new version. However, sometimes it's avoidable, and if you need a brand new data contract, you'll need a new version of your endpoint. So you'll need to communicate that to the public in some way.

As an aside, do note that we're not talking about the version of the underlying code base. So if you're using semantic versioning for your application that also supports a public API, you will likely want to separate those versioning systems.

How do you create a new version of your API? What are the different methods for doing so? You'll need to determine what type of versioning strategy you want to take in general, and then as you develop and maintain your API, you'll need to determine the scope of each version change.

Scope

Let's tackle scope first. As we explored above, sometimes data contracts will be compromised by a breaking change, and that means we'll need to provide a new version of the data contract. That could mean a new version of an endpoint, or it could mean a change at a more global application scope.

We can think of levels of scope change within a tree analogy:

• Leaf - A change to an isolated endpoint with no relationship to other endpoints
• Branch - A change to a group of endpoints or a resource accessed through several endpoints
• Trunk - An application-level change, warranting a version change on most or all endpoints
• Root - A change affecting access to all API resources of all versions

As you can see, moving from leaf to root, the changes become progressively more impactful and global in scope.

The leaf scope can often be handled through effective API change management. If not, simply create a new endpoint with the new resource data contract.

A branch is a little trickier, depending on just how many endpoints are affected by the data contract change on the resource in question. If the changes are relatively confined to a clear group of related endpoints, you could potentially navigate this by introducing a new name for the resource and updating your docs accordingly.

# variants, which has a breaking change, is accessed on multiple routes
/variants
/products/:id/variants

# we introduce product-variants instead
/product-variants
/products/:id/product-variants

A trunk refers to application-level changes that are often a result of a change in one of the following categories:

• Format (e.g. from XML to JSON)
• Specification (e.g. from an in-house one to JSON API or Open API)
• Required headers (e.g. for authentication/authorization)

These will necessitate a change in your overall API version, so you should plan carefully and execute the transition well.

A root change will force you to go one step further in ensuring that all consumers of all versions of your API are aware of the change.

Types of API Versioning

As we turn to different types of API versioning, we'll want to use these insights into varying scopes of API changes to evaluate the types. Each approach has its own set of strengths and weaknesses in addressing changes based on their scope.

There are several methods for managing the version of your API. URI path versioning is the most common.

URI Path

http://www.example.com/api/v1/products
http://api.example.com/v1/products

This strategy involves putting the version number in the path of the URI, and is often done with the prefix "v". More often than not, API designers use it to refer to their application version (i.e. "trunk") rather than the endpoint version (i.e. "leaf" or "branch"), but that's not always a safe assumption.

URI path versioning implies orchestrated releases of application versions that will require one of two approaches: maintaining one version while developing a new one or forcing consumers to wait for new resources until the new version is released. It also means you'd need to carry over any non-changed endpoints from version to version. However, for APIs with relatively low volatility, it's still a decent option.

You would likely not want to relate your version number to that of the endpoint or resource, because it would easily result in something like a v4 of products but a v1 of variants, which would be rather confusing.

Query Params

http://www.example.com/api/products?version=1

This type of versioning adds a query param to the request that indicates the version. Very flexible in terms of requesting the version of the resource you'd like at the "leaf" level, but it holds no notion of the overall API's version and lends itself to the same out-of-sync issues mentioned in the above comment on endpoint-level versioning of the URI path.

Header

Accept: version=1.0

The header approach is one that provides more granularity in serving up the requested version of any given resource.

However, it's buried in the request object and isn't as transparent as the URI path option. It's also still hard to tell whether 1.0 refers to the version of the endpoint or the API itself.

Integrating Types

Each of these approaches seem to have the weakness of either favoring a "leaf" or "trunk" scope, but not supporting both.

If you need to maintain the overall API version and also provide support for multiple versions of resources, consider a blend of the URI Path and Query Params types, or a more advanced Header approach.

# URI path and query params combo
http://api.example.com/v1/products?version=1
http://api.example.com/v1/products?version=2

# Extended headers, for http://api.example.com/products
Accept: api-version=1; resource-version=1
Accept: api-version=1; resource-version=2

Conclusion

We've covered a lot of ground here, so let's recap:

• API versioning is the practice of transparently managing changes to your API.
• Managing an API boils down to defining and evolving data contracts and dealing with breaking changes.
• The most effective way to evolve your API without breaking changes is to follow effective API change management principles.
• For most APIs, versioning in the URI path is the most straightforward solution.
• For more complex or volatile APIs, you can manage varying scopes of changes by employing an integration of URI path and query params approaches.

Although these principles should provide clear direction in how to effectively manage change to your APIs, evolving an API is potentially more of an art than a science. It requires thought and foresight to create and maintain a reliable API.

Why backwards compatibility matters

(If you're already convinced that API stability is a crucial concern, not the whim of a few conservative mummies, save yourself some time and rush to the following chapter.)

"WE DO NOT BREAK USERSPACE!"

This famous rant of Linus Torvalds is, alas, more relevant than ever.

If a change results in user programs breaking, it's a bug in the kernel. We never EVER blame the user programs. How hard can this be to understand?

If applications didn't care about specific error values, then it wouldn't make sense to have more than one to begin with, and you shouldn't care which one that was. But since applications do care, and since we do have multiple error values, we stick to the old ones, unless there are some very good reasons not to. And those reasons really need to be very good, and spelled out and explained.

Let's replace "kernel" by any framework/library, and "error value" by "API signature", and we get an invaluable commandment of good programming. We can live quite well with a few buglets and imperfect features, but when our applications deliver segfaults or lengthy tracebacks after a simple version upgrade, there is a problem. A real problem.

And there is a paradox here. Regarding OS distributions, drivers, libc/gtk/Qt and other low-level, statically typed libraries, we expect - and are happy to experience - painless updates, bringing only new features and bugfixes. Whereas for our high-level web frameworks, mostly coded in dynamic languages, we have become resigned to the fact that each update could become a 3-days labor of understanding breakages, finding compatible versions of dependencies, and forking or monkey-patching until test suites are green again. Logically, shouldn't it be the other way round ? Why are most 1995 win32 freewares still working, why was the x32/x64 migration so transparent for most users, if a pluggable server app released 2 years ago is broken on multiple aspects?

I'll tell you why.

API stability was once a very praised commitment. Semantic versioning was a must-have. Projects like Qt proudly detailed the measures they took to ensure their C/C++ would evolve without breakage. Some even filled their function parameters with NULL values "reserved for future uses". And incompatible changes were only evocated when no solution could be found.

Luckily, this mindset is still valid in large areas of programming. But now a different philosophy has contaminated minds, especially in the web industry. This spartan way of thinking could be called "Walk or die", "No paradise for the weak", or "As long as I warn, I can shoot the bullet". Sometimes hiding behind cute concepts like "calendar versioning", or "evergreen applications", this way of thinking is actually crystal-clear: the most minor software upgrade may introduce breaking changes - documented or not, proudly assumed or not - just deal with it.

Why? Why not just let aliases, adapters, and other compatibility shims, when moving modules around, when renaming objects, when changing function signatures? With the dynamic and introspective nature of most modern languages, isn't that a breeze? Sometimes development resources are so scarce that it's already too much. But the rest of the time? My guess is that when it is not a problem of technical skill, or of laziness, it might be a cultural issue.

Do you know this dopamine hit you get when you tick a box in a checklist, especially the last one? This satisfaction that sometimes makes you write an already completed task just so you can tick it? You might get the same thrill when you brutally refactor code to a cleaner architecture, or erase compatibility shims "as per deprecation policy". It's the happiness rush of the duty well done, of the return to purity.

But this precise feeling is a huge lie. A blinding self-absorption. A harmful psychological bias.

Compatibility shims are not technical debt; nor a set of warts. At the very contrary, they are invaluable assets. With these few chunks of source code, our software extends its compatibility to tens, hundreds, thousands of miscellaneous libraries and applications spread across the web, in both public and private repositories, ranging from tiny utilities to huge corporate applications. These foreign codebases, full of business logic, of money-bringing features, of highly specific code, are what make their foundations worth existing.

But this ecosystem is of an extraordinary diversity. Some repositories get commits every day from multiple contributors, some get a mass update once in a while when their maintainers get a little spare time, and some have not been touched for years (because their creator lost interest, or just couldn't find anything to improve). Some have Tox-like multi-version testing and continuous integration, some don't even have a single unit-test.

So what happens when developers follow this trendy "Walk or die" philosophy? The ecosystem, already heavily fragmented by language (python2vs3, ruby, go, php... just for dynamic languages), by file format and network protocol, by framework and execution style (sync vs async), gets fragmented even more. In the most silent and deadly way. Basically, if we consider the codebases depending on a framework or library (here called "the software"):

• Repositories that haven't been updated for a few years are broken by default.
• Repositories that are actively maintained, but do not target the same software version as us, do not work either.
• Bug trackers get filled with useless "Plz add support for version X.Y.Z" or "Plz restore support for version X.Y.Z" tickets.
• Forks flourish around mildly renowned repositories ; forks which can't be merged back, since each of their modifications are highly likely to break things for other software versions ; and the subsequent improvements brought by each forker, being chained to divergent codebases, keep spreading without ever being merged back ; naturally, they get remade by several developers each on his own, since few of them take the time to review the forks graph and cherry-pick interesting commits.
• Biggest projects sometimes get nice enough to provide a compatibility matrix, or "known working sets" pinned down to their patch version number. But as soon as you have more than a few dependencies, you enter a dependency hell that no conflict resolution algorithm can tackle ; you just have to fork, fork, fork, and monkey-patch, until your dependencies find an agreement.
• Project requirements get filled with links to git repository and commit hashes; semantic-less data which will make the next upgrades still more awkwardly experimental; or which will disappear due to an unexpected "force-push".
• Without surprise, many maintainers of these pluggable apps don't want to take on them the additional burden of filling their code with special cases, to work around the breakage frenzy of the main software's developers. As a result, the dependency hell keeps expanding unrestrained.

So when proudly pluralizing the name of a submodule, when removing a purportedly little-used utility class, when making an optional argument become mandatory, we're not improving anything. We're just murdering practicality for the sake of aesthetical purity. We're recklessly destroying entire regions of the software ecosystem, turning gazillions of test suites into reddish nightmares. But we'll never know to what extent; especially if we don't check. Ignorance is bliss.

Biological ecosystems can reach down to the depth of the abyss or to other planets if they have plenty of time; when things change too quickly, it's mass extinction. Software ecosystems are no different. Enjoying the cleanliness of an API "remade from scratch" is like enjoying the microbial sterility of a forest vitrified by a nuclear blast.

For sure, it's a falsehood to think that because we use some open-source software, we're entitled to getting the bugfixes and features that we request. But it's equally false to think that because the users of our framework/library are not paying clients, we owe them nothing. They trusted us, built their own code against ours, followed our conventions and best practices, when they could have chosen another language/framework/library. How can we justify trampling their own efforts, making them waste days or weeks of development, just because we suddenly felt the irrepressible urge to change a naming scheme, or drop perfectly working code? We're all interdependent in a software ecosystem, and a tiny dose of awareness, carefulness and rationality can go a long way. "But you're never sure that a change doesn't break things", some will shrug. Sure. No one demands perfection. But not being deliberately harmful is already a very good start.

There is like a paternalistic mood behind some advocates of the "walk or die" approach. "If we stick to API stability, contributors will get lazy and never update their modules, the ecosystem will rot in place instead of moving forward". Oh damn, how dangerous it is, to do people's good against their will. If we want users to update their codebase, at the very contrary, we should start by not brutally breaking things. We should bring shiny new features, not just a gun to their head. We should let them fix mildly annoying "deprecation warnings" when they feel like and can, not right now. We should let them spend their time on useful contributions, not on repairing what we have broken with the planned obsolescence that we dare calling "progress".

Fun facts: advertising breaking changes in release notes does not grant them legitimacy; and when a private API is so handy that it's used by multiple projects, maybe it's a sign that it should be made public and documented, not that it should be wrecked at the first impulse.

So let's carve it into the marble of our desktops: API stability is, must be, on top of our list of concerns; along with robustness and adequation with final users' needs; but infinitely above any kind of aesthetical consideration. Only with long-term compatibility may our software ecosystems grow from a short elite of continually updated applications, to a huge and diverse galaxy of modules; some last- updated yesterday, some last-updated ten years ago, but all of them getting stuff done. Because that what software is all about, and that's what people are being paid for, at the end of the day. Not wasting time fixing the wheel that worked yesterday, and won't tomorrow ever more, because we heard the calling of the void.

The Compat Patcher concept

Am I asking (open source) software maintainers to make more efforts, in order to achieve this so crucial long-term API stability? Nope. I wouldn't dare. At the contrary, I ask them to be lazier. But the good, the sensible, the both self-interested and benevolent, kind of lazy.

More compatibility means less support requests, less time justifying controversial changes, and more feature/bugfix contributions from our community. More compatibility doesn't even mean more keyboard typing. Except if we're only into toy projects, we've already put compatibility shims in place for a time. Just one thing to do : leave them be. They don't hurt us. They don't waste disk space. They are probably worth thousands of dollars per character. Let's just avoid one savage "Removing compatibility shim XYZ" commit, and move on towards greater goals.

And if the mere view of a compatibility shim makes us vomit (a not so unusual pathology I guess), there is awesome news : with high-level languages, we don't need shims in our code anymore. We just have to embrace the concept of Compatibility Patcher (or "compatcher" for neologism lovers).

Wat-iz-dat ? Just a companion library, often living its own life in its own repository, which plugs itself to the real software at startup time, and restores its compatibility with a decade of its previous versions. Thus, we can keep our codebase entirely unaware of whatever a "deprecation" might be, while still keeping a symbiotic coexistence with the thousands modules living in our ecosystem.

Monkey-patching is ugly, someone said? Maybe, but never as ugly as spending hours retro-engineering a whole plugin architecture, just to realize that an additional "S" in naming conventions sufficed to ruin everything. Programming overlords might prefer to weave their code with external shims using aspect-oriented programming, but for most of us mere mortals, simplicity and pragmatism are widely sufficient enough. Some documentation, logging, and console warnings, are "explicit" enough to make anybody keep control over the codebase.

Let's not underestimate the power of high level languages. Examples with Python. We rename a submodule? Fine, thanks to import hooks, "from framework import oldmodule" and "from framework import newmodule" will return the exact same object. We change the signature of a function ? One tiny injection later, the old set of call parameters will automatically be adapted and forwarded to the new signature. We move an entire group of utilities out of the main repository? Fine, but as long as needed, the compatibility patcher will fetch them from their new location, and inject them back where they once so nicely belonged. We rename constants, classes, functions ? Leaving an alias was only costing a single code line, now with compatibility patchers this line doesn't even have to hurt our eyes and hearts anymore.

Please notice, Compatibility Patchers act like time travelers. They work even when developers delete a function, re-add it under a different shape, then remove it again. They work even when developers recklessly modify function behaviours, for example by exchanging similar arguments in-place. So imagine when developers cooperate with this system, and nicely decouple programming concerns so that the patch is minimal!

Cherry on the cake, by separating "state of art" code and compatibility shims, Compat Patchers make it a breeze to selectively activate compatibility sets. Your project is brand new and only relies on bleeding edge libraries ? Fine, deactivate the whole patcher. You just need compatibility with the last two major versions of the framework? Just enable the corresponding families of shims. You need support for very old packages ? Leave the patcher configuration in maximal mode.

That feeling when all 30 dependencies work smoothly on first install

Now comes the anxiety-provoking part : what are the downsides of Compat Patchers? Answer: up to a few seconds of delay at startup (when all shims are activated), and a few logical operations and type checks here and there at runtime. That's it. In the modern web world, where most server processes run for hours uninterrupted, process the most unoptimized (text-based) formats conceivable, and where performance depends much more on DB optimization and proper caching than on raw execution speed, it sounds like a legitimate expense, doesn't it?

Edit: another limitation of Compat Patchers is that they require a tiny little bit of cooperation from core developers. Indeed, we all implicitly know the rule of backwards compatibility: "Only Add Optional". Add new optional arguments, add new functions, add new modules; don't remove elements and behaviours, don't make old options mandatory. But there is an additional, golden rule: don't ever, ever, change the semantic of things in-place. If we change the meaning of an argument, the format of an output, the action of a callable, without any additional indicator, then setting up shims becomes (almost) unfeasible; in this case, even Compat Patchers won't be able to resolve this ambiguity, and guess the behaviour that our users were requesting when using our API. Let's blacklist forever these kinds of brutal and inimical changes.

Time for practice!

Compat patchers are not just wishful thinking.

Here is one for the famous Django web framework. With a few dozens of small fixers, it allows one to use pluggable apps targeting from versions 1.6 to 2.2 of the framework. And it's only a start - feature requests and comments are welcome.

This patcher is used in production on a few sites, including the Pychronia portal and its CMS/Blog ecosystem. It runs on CompatPatcherCore, a Python micro-framework for creating such companion applications in the blink of an eye (a cookiecutter recipe is even included).

Without surprise, I warmly encourage you to bootstrap a Compat Patcher for the framework/library you might maintain, unless you are one of the few valiant minds already strongly committed to API stability.

This concept should also be easy to port to Ruby, PHP, Javascript, and other high-malleability languages. With lower-level and static languages, the task might be much harder (and require macro processors and the likes), but who knows.

So here we are. Update breakages are not a fatality. Just a bad habit that we must break, thanks to a little pondering and a few technical niceties. We may thus enjoy the delights of ever-growing and ever-working software ecosystems, those which do make development fun and exciting!

Edit 2019/07/05: Evocate the "hard scarcity of resources" as a possible reason for lack of shims, and tweak the tone of this part.

Edit 2019/07/14: Fix typos, and warn against in-place semantic changes.