The compatibility_level conundrum

[Wyverald]

From time to time, libraries make breaking changes. Downstream projects can then get broken when all they did was upgrade a dependency on a library to a newer version.

To combat this, Bazel has the compatibility_level concept, roughly corresponding to the "major" version of SemVer. Supposedly, a breaking change should be accompanied by an increase of the compatibility_level. In practice, however, this field is rarely updated, since Bazel throws an error when multiple versions of a the same module exist in the dep graph, and those versions have mismatching compatibility levels.

Nobody likes this situation. People hate it when compatibility levels aren't bumped: breaking changes aren't signaled in any way, so a downstream project gets broken on a simple dependency upgrade. People also hate it when compatibility levels are bumped: it causes a cascading "sweep" of the entire ecosystem, where all transitive dependents of the library have to acknowledge the compatibility level bump one way or another.

If anyone has ideas on how to improve the situation, please share them here!

More color

• Any change is potentially a breaking change. It's really hard to say what amounts to a breaking change (relevant: https://xkcd.com/1172/). Some say only large scale API changes count. Others say behavioral changes also count. Overcounting results in breakages when upgrading: this change doesn't affect me at all! Undercounting also results in breakages when upgrading: this change broke me, but Bazel didn't tell me!
• bazel_dep.max_compatibility_level helps. This field was added in Bazel 6.2.0, and allows a module to declare its tolerance of a version upgrade up to certain compatibility level skips. It's no panacea, but can lessen the pain if enough modules in the ecosystem diligently specify it.
• Compatibility level bumps are transitive. Say A is a dependency of B. When a new version of A bumps its compatibility level, the next version of B needs to make a choice: does it bump its own compatibility level? If not, then a dependent of B (let's call it C) could in turn be faced with a mysterious failure when it decides to upgrade B, just because C has a dependency (or worse, a transitive dependency) on the older version of A. But if B bumps its own compatibility level, it'd just be passing the problem down the line.

[fmeum]

When a new version of A bumps its compatibility level, the next version of B needs to make a choice: does it bump its own compatibility level?

I think that B really shouldn't bump its compatibility level in this situation:

• If C directly depends on (an older version of) A, then it is its "duty" as a direct dependent to check and declare (via max_compatibility_level) that it also supports the newer version of A.
• If C only depends on A transitively, then it should update to versions of its direct deps that themselves correctly declare that they work with that new version of A.

None of this gets better if B also bumps its compatibility level and the pain that A's bump causes is distributed in the expected fashion: direct dependents of A need to take action specific to A, everyone else "just" needs to keep their direct deps up-to-date.