How to handle breaking changes

[nicl]

(Migrated from #909.)

As more people use the library and things mature, we'll want to become more cautious to introduce breaking changes. SemVer is great, but it's not much use if we continue to release breaking changes at a high cadence.

So how do we handle this?

I'm particularly keen to discuss changes to the APIs we expose, rather than the underlying snapshots that are produced here, although the latter is important too.

Why is this important?

• breaking changes create a burden on teams to upgrade, remember there are 100s of projects that will eventually use CDK so any breaking changes are likely to incur a lot of work across the dept
• because they make upgrading harder, breaking changes will slow adoption of new patterns/constructs (as people won't be able to easily move to the latest version of our library)

There are some implications of this:

• we should strive to avoid breaking changes, and be willing to support old patterns/props etc for long periods of time
• if we need to make drastic changes to many existing patterns or constructs, we should create a new package (e.g. -v2) with a different import path
• we should aim to make patterns general-enough that we can change background details without changing their API - e.g. specific solutions for logging/config/etc. shouldn't be exposed in the pattern, but implemented by it behind the scenes, with only a very general interface presented.

@SiAdcock has kindly shared the Source approach below, and there are some points to note:

• a strong desire to avoid breaking changes wherever possible ('one or twice a year')
• migration guides and even automation (they do this with eslint rules)
• a fantastic dashboard/metrics to track adoption

---

Notes from @SiAdcock on how Source do it:

*Hi Nic!

Breaking changes entail a major version bump, which is a Big Thing in Source. This might happen twice a year.
We tend to avoid making breaking changes for as long as possible. Eventually we need to do it, but usually as part of a larger milestone (e.g. consolidating a bunch of packages into one package, upgrading peerDependencies). We could and often do throw in some "extra" (smaller) breaking changes at the same time, but we're keen to not create a huge burden for teams to upgrade.

We always write a migration guide, but for the most recent major version bump (v4) we also created ESLint plugins that you can install into your project and add to your .eslintrc. Running eslint with the --fix flag automatically "fixes" things that have changed in a breaking way.
https://github.com/guardian/source/tree/main/packages/%40guardian/eslint-plugin-source-react-components

We also have a dashboard that tracks the versions of Source that are being used across all Guardian products. This informs us on how teams are managing upgrades, and can feed into discussions around the cadence of new major releases, whether teams need more helping upgrading and whether we can de-support older versions
https://metrics.gutools.co.uk/d/-RNkA4jMz/devx-source-usage?orgId=1

These discussions are informal at the moment, but we could put in more formal rules to drive these decisions now that we have tracking in place.*

[akash1810]

There's a wider problem to solve here regarding how we bump library dependencies. Whilst some repositories have Dependabot configured, it's PRs don't always get reviewed/merged. We can commit to releasing fewer breaking changes as adoption increases, however we want to be sure that patch and minor updates get adopted early and regularly.

There is much less risk in "blindly" merging in Dependabot's PRs for patch or minor updates of @guardian/cdk as it is not client-side focused and is only concerned with a single environment/user agent - AWS. That is, we need to improve culturally.

[akash1810]

cc @guardian/client-side-infra

[akash1810]

👍🏽

There will always be some breaking changes, such as when updating the version of AWS CDK being used or as best practice or InfoSec requires evolve (e.g. the Wazuh programme).

I suspect/hope as adoption increases and the shape of the library reaches maturity, the rate of breaking changes will naturally slow.

[nicl]

https://docs.aws.amazon.com/cdk/latest/guide/work-with-cdk-v2.html is an interesting read here re upcoming v2 of the AWS CDK library. Some things to note:

• they are using naming and separate 'alpha' packages for experimental patterns and constructs (a bit like Source Kitchen perhaps?)
• a novel 'BetaN' mechanism to add new methods/properties and iterate without breaking your stuff (this is difficult to explain concisely but quite interesting - so worth a read)
• deprecated things from v1 are now removed (after quite a long time)

In general, the care they are taking to avoid breaking things is significant. Obviously, we don't need to be as thorough but still food for thought.