Breaking Changes

Defining what constitutes a breaking change isn't easy for integrated tools like Nx.

There are two extremes:

• For a runtime library, you have a well-defined interface and then you can make assertions against. This, of course, doesn't guarantee that a code change won't break anyone. Any code change can break someone somewhere, even if it is a small bug fix. After all, someone could reply on the existence of the bug. I.e., it's about probabilities and not guarantees.
• For a IDE or an editor, you cannot meaningfully define "a breaking change" because the interface is graphical and it's hard to formally define it. That's why, for instance, VSCode and Intellij don't use semantic versioning.

Nx sits someone in between. These are the guidelines we use:

• Nx Commands (e.g., affected). We are in full control of this, so we are trying to make sure that absolutely no-one is broken. This doesn't always works. For instance, changing the command output to use colors broke some folks because they parsed the command outputs in CI. We added a flag to help with this.

• Schematics. It's hard to define the interface of a schematic. When it comes to inputs, we are trying to treat them like an interface. We don't remove flags or introduce new mandatory flags in minor releases. The outputs, the generated code, can be used in many different ways, it's hard to make any formal assertions about it. So we are simply trying to do our best and not change the generated code drastically in a non-major release.

• Builders. when it comes to inputs, we are trying to treat them like an interface. Builders often delegate to external tools, and not all of them use semantic versioning. So we cannot guarantee that a minor update won't break you, but we do our best.

• Runtime Components. It's a runtime library, so we treat it as such.