Member-only story
How To Deprecate APIs the Right Way
Deprecate your old APIs with the consciousness of your users
The only certainty in software development is that requirements change.
How many times has this happened to you? You start a project, develop an app to satisfy the requirements, release it, and everyone is happy. The product manager comes back and asks to add a new feature. Suddenly, you have to pass an extra parameter or change the name of a property. You make the change, and other parts of the app start erroring, even parts handled by other teams.
Whether you are working on a library, a framework, or even just a module of an app, you need to be considerate of all of its possible consumers. If you introduce a breaking change, you must give your users the time and tools to adjust their code.
Today, I want to explore what is a breaking change, what kind of changes can be considered breaking, and what techniques can be used to propagate those changes safely.
What Is a Breaking Change?
A breaking change is a change in the code that requires other parts of the code to change to keep the system working.
The simplest example is when you change the name of a property in a public API: every other component that uses that property has to update the name to the new one.
Breaking changes could happen at different levels:
- Code changes: changes in the signature of some public or protected API. They usually trigger some errors in the compiler.
- Behavior changes: changes in how some code behaves. These are subtle, as the code could continue building without errors, but the final results are different from the previous version. For example, once Apple changed from the Swift version to another, the order of the
keysreturned by theDictionary.keyproperty. This makes some snapshot test fail because the reference test was obtained with the old version of the system. - Build system changes: changes in how files are built or on the flags that need to be passed to the compiler. If, from one version to the other, you change how the app needs to be configured to build, old versions of the app won’t build on new versions…
