You're responsible for a widely-consumed internal library published to hundreds of services inside a large engineering org. Design a policy that lets SemVer's MAJOR/MINOR/PATCH numbers actually stay trustworthy over years of contributions from dozens of different teams, given that no single person reviews every change. What mechanisms would you put in place, and what's the failure mode of skipping each one?

## Why one person's judgment stops scaling At small scale, SemVer compliance is a single maintainer's judgment call, exercised consistently because one person (or a tiny core team) reviews every change against a mental model of the whole public API. That model breaks down completely at organizational scale: once dozens of teams contribute to a shared internal library over years, no individual reviewer has full visibility into every consumer's dependency on every corner of the API, and 'did I just break something' becomes a question that can't be reliably answered by inspection alone. Making SemVer trustworthy at this scale means replacing individual judgment with process and tooling wherever possible, and reserving human judgment for the cases tooling genuinely can't resolve. ## The five mechanisms, and what skipping each costs 1. **The first mechanism is a written, checkable definition of the public API surface itself** — without this, 'breaking change' is undefined, because reviewers disagree about whether an internal helper class that some other team imported anyway counts. Concretely this means a convention (an internal/impl package namespace, explicit annotations, or a maintained allowlist of exported symbols) that both humans and tooling can check against, so the compatibility promise has a bounded, unambiguous scope rather than covering 'anything anyone might be depending on,' which is unbounded per Hyrum's Law and impossible to fully protect. 2. **The second, and highest-leverage, mechanism is automated API-diffing in CI**: a tool that compares the previous published API surface against the PR's resulting surface and classifies the change as breaking, additive, or internal-only, independent of what the author believes they did. Ecosystems have mature tooling for this — binary/source compatibility checkers for compiled languages, and schema-diff tools for network APIs like OpenAPI or protobuf — and the mechanism matters because it converts SemVer compliance from a self-reported claim into a build-time fact. Skipping this step means the org is back to trusting every individual contributor's classification, which historically fails the way the automated-upgrade-trust problem does more broadly: well-intentioned engineers mislabel changes, especially ones involving default values or validation tightening that don't look like 'API changes' from a casual diff view. 3. **The third mechanism is a distinct approval gate**, separate from ordinary code review, for anything the diff tool flags as breaking — typically owned by a small API-owner or architecture-review role rather than whichever team happens to be touching the code that week. This matters because a routine PR reviewer optimizing for 'does this code work' is not the same lens as 'should this ship as a MAJOR bump and who does it affect downstream' — the second question requires visibility across consumers that an individual code reviewer usually doesn't have, so it needs to be routed to whoever does, or to tooling that can enumerate known internal consumers via a reverse-dependency graph. 4. **The fourth mechanism is a deprecation-window policy**: mark a symbol deprecated with a machine-readable annotation and a target removal version/date, keep it functioning for a minimum supported period, and only then remove it in a MAJOR bump that consumers had advance warning about. Skipping this turns every removal into a same-release surprise — technically still a correctly-labeled MAJOR bump, but one that gives consumers zero lead time to migrate, which defeats much of the practical value of the compatibility promise even when the version number is technically accurate. 5. **The fifth mechanism is generating the changelog from the same classification data the diff tool produced**, rather than a hand-written summary assembled after the fact from memory of what changed. Hand-written changelogs drift — engineers forget to mention a default-value change because it didn't feel like 'a change' worth writing up, and the gap between the changelog's story and the version number's actual meaning grows over years until consumers stop trusting either. ## The trade-off The overarching trade-off across all five mechanisms is **upfront tooling/process investment versus long-run trust**: each one requires real setup cost that's easy to defer when the library is small and the org is small. ## What deferring all of it looks like The failure mode of deferring all of it isn't a single dramatic incident — it's **gradual erosion**: version numbers technically increment correctly by author intent, but enough misclassified changes accumulate that consumer teams stop trusting MINOR/PATCH bumps to be safe, start manually reviewing every dependency bump regardless of version number, and the entire point of having a SemVer contract — safe, low-friction automated upgrades — quietly stops paying off, even though nothing about the process ever visibly 'broke.'