As a growing startup with a strong focus on moving fast — adding new features and extending existing product services are part of our daily routine and vital to growth.

But with every new addition, there is always one thing that never changes, the possibility of breaking the product or service. For this, we plan and design every new feature meticulously to make the development phase smoother and reduce the probability of introducing a breaking change.

And let’s face it! Breaking changes will become one of the factors affecting the goals and morale of the team if these are frequent. So this becomes a big question...

How a feature becomes a breaking change?

There could be an ‘n’ number of factors that can turn a new feature or related code into breaking change. It could be —

• An infrastructure issue or bottleneck
• unreviewed or poorly written code
• lack of basic error handling
• untested or missed areas in the feature during the QA cycle
• OR simply a human error — To error is Human!

Irrespective of factors having a plan to mitigate and minimize the breaking change becomes integral to delivering any feature successfully on time.

So we start by stating the obvious —

What is a breaking change?

Knowing what can result in breaking change is the first step to weed out the breaking changes during the development and code review phase.

Most of the time these factors are closely related to fundamentals of technology - frontend or backend, tools that are used for writing the feature or code. To name a few following are some examples -

Common examples for backend include:

• Removing a resolver or field resolver
• Removing a response field
• Updating a resource or method URI
• Updating a field name
• Updating required query parameters/inputs
• Updating authorization

Common examples for backend include:

• Removing a resolver or field resolver
• Removing a response field
• Updating a resource or method URI
• Updating a field name
• Updating required query parameters/inputs
• Updating authorization

What is not a breaking change?

Just as knowing what is a breaking change? It is equally important to know what is not a breaking change?

This is important for code reviewers along with independent contributors as this gives confidence that a newly written block isn’t a breaking change, and we can ship it on time.

Common examples of additive, non-breaking changes include:

• Adding a new resolver or field resolver
• Adding a new response field
• Adding optional query parameters / inputs

Some exceptions - adding required query parameters/inputs to an existing endpoint — are breaking change.

Measures to prevent breaking changes

Once we know - what is and what is not a breaking change, we can come up with a list of rules which can be included in our development workflows from the very start till the end of delivery of the feature.

1. Take some time to plan the feature and identify the changes that may turn it in the breaking change. Once identified categorize the nature of breaking change —

• Low risk
• Medium risk
• High risk

and start working towards the possible solution to fix it.

2. Discuss and communicate new change with original code author(s) before starting the feature**.** To make sure we don't break or remove something from existing feature.
3. Always try to request and get a review from the original author and people who know about the area which is impacted by the introduction of the new feature.
4. Test your change for accidental breaking changes before pushing it to staging environment.(worst case prod). Ideally one should only push the change after verifying the Happy flow of the feature.
5. Along with introducing the new feature, provide support for the old feature for a set period to allow smooth transition to new feature. By,

• Using Breaking Change as a tag for pull requests with GitHub, similarly Breaking-Change with JIRA and tag stakeholder dev’s for better visibility.

• Using @deprecated header/badge/tag to give clients (web or app) more time to react.
• Communicate all the consumers, If there are multiple clients consuming the service to make avoid last moment rollbacks or fixes.

6. Set clear timelines and have clear communication

That said above points will only be useful if everyone from the team knows about the feature and changes ahead of time so that it gets reviewed, tested correctly, and finally makes to prod happily.

And as a part of the process, we keep tinkering with this approach to make feature deliveries smooth and perfect so keep an eye for future updates!