Have you ever had to upgrade a package dependency that was a major release? You read the changelog, you saw all that breaking changes, and it was a nightmare to upgrade your codebase.

A Breaking change is when some existing behavior changes in a way that would require a user to change their code in order to upgrade to the new version.

Breaking changes do not only happens on external dependencies, but also inside your own codebase. Without breaking changes, you can move faster and avoid unexpected behavior changes.

This article is a guide of how to avoid breaking changes in many places of your software development

Backend vs Frontend

When making a breaking change, you cannot assert that the server will be aligned with the frontend version. For example:

You have a field in your GraphQL being consumed in your frontend. Then, you remove this field from your GraphQL schema. You also remove from the frontend.
However, the browser cached your frontend assets, so users with a cached version of your frontend still are consuming the removed field, causing an error for them until they upgrade to the latest frontend version.

I saw a lot of this type of breaking change, it causes us in the past more than 100k errors.

REST endpoint breaking changes

• removing a field from a response is a breaking change
• changing validation of a request body is a breaking change
• marking a field as required in a request body is a breaking change

GraphQL breaking changes

• removing a resolver is a breaking change
• removing a mutation/subscription is a breaking change
• marking an optional field as required is a breaking change
• marking an optional input type as required is a breaking change
• changing a field type is a breaking change

Function breaking changes

• changing a function signature is a breaking change
• adding an optional argument to a function is not a breaking change

Relay breaking changes

• changing connection name can be a breaking change, you need to update all places that used these connections, usually on mutations

When to make a breaking change?

Sometimes you need to make a breaking change to move forward.
If you need to change the function signature to make it more flexible, you need to find the usages of this function, where this function is used.
Then update all the usages to use the new function signature.

How to make breaking changes less painful?

To make breaking changes less painful, provide a migration guide for the breaking change. In addition, you can provide a codemod to transform old code to the new code format.

What else can cause a breaking change ?

Woovi is a Startup that enables shoppers to pay as they like. To make this possible, Woovi provides instant payment solutions for merchants to accept orders.

If you want to work with us, we are hiring!

Photo by CHUTTERSNAP on Unsplash