1 views
# Semantic Versioning in Practice: What Actually Counts as a Breaking Change Semantic Versioning (MAJOR.MINOR.PATCH) is simple on paper: bump MAJOR for breaking changes, MINOR for new backward-compatible features, PATCH for backward-compatible fixes. The hard part is deciding what "breaking" means. ## Clearly breaking - Removing or renaming a public function, field, endpoint, or CLI flag. - Changing a function signature or required arguments. - Tightening validation so that previously accepted input is now rejected. - Changing a default that callers silently relied on. ## Gray areas - **Bug fixes that change behavior**: if users depended on the buggy output, a "fix" breaks them. Many projects still ship this as PATCH but call it out in release notes. - **New required config or environment variables**: breaking for operators even if the API is unchanged. - **Dropping support for an old runtime** (for example an old Node or Python version): most libraries treat this as MAJOR. - **Adding an enum value**: harmless for producers, but consumers with exhaustive switches may break. ## The 0.x escape hatch Before 1.0.0, anything may change. Tools like npm's caret (`^0.4.2`) treat MINOR as breaking in 0.x. Do not stay on 0.x forever just to avoid commitment; users read it as "unstable." ## Habits that help - Keep a CHANGELOG with a "Breaking" section. - Deprecate first: emit a warning in one MINOR release, remove in the next MAJOR. - Run API diff tools (api-extractor, cargo-semver-checks, japicmp) in CI. - Lock files protect apps; libraries should declare ranges, not exact pins. Versioning questions show up in interviews for platform and library roles. For rehearsing explanations like this, I build [this tool](https://www.linkjob.ai/), Linkjob AI.