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
Top comments (2)
Break changes are tough, but it’s good from my point of view in general to use a different approach while dealing with them, for example when trying to introduce a breaking change, try to have it in a way it’s not a break change, like introducing a new mandatory field, could start in a transition period with it as “optional” that would allow adoption without a break change, later on you can make it required as the adoption increase.
Depending on the size of your project and who is consuming for example your api, strongly recommend monitoring of such usages só it makes life easier to notify consumers about deprecation and updates
That's a good take
You usually should use a Tick Tock migration approach like this dev.to/woovi/tick-tock-migration-p...