intermediate

Semantic versioning

Communicate compatibility through major, minor, and patch versions tied to API and behavior changes.

Semantic Versioning (SemVer) communicates compatibility with `MAJOR.MINOR.PATCH`:

| Bump | Meaning | |------|---------| | MAJOR | Breaking change to public API or behavior consumers rely on | | MINOR | Backward-compatible new capability | | PATCH | Backward-compatible fix |

`0.y.z` releases are unstable by convention—breaking changes may ship in minor bumps. Peer dependency ranges in libraries must align with semver promises.

On interviews: define public API, classify behavior changes types may still compile through, deprecation policy, and internal package semver for other teams.

Common pitfalls: breaking changes labeled patch; semver on libraries with undeclared public surface; fixing consumer bugs by breaking API without major bump.

The trade-off is clear consumer expectations versus release friction for breaking migrations.

Checklist:

Document public API boundary.
Classify behavior vs type-only changes.
Communicate migrations in changelog.
Align peer ranges with compatibility story.