# 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.