Glossary / Semantic versioning

Semantic versioning

Semantic Versioning (SemVer) is a convention for communicating compatibility through version numbers in the form MAJOR.MINOR.PATCH, with pre-release and build metadata extensions. It is useful only when projects consistently define and honor what counts as a public API and a breaking change.

Version components

For a released 1.4.2, 1 is the major version, 4 minor, and 2 patch. Under SemVer 2.0.0, patch releases are for backward-compatible bug fixes, minor releases add backward-compatible functionality, and major releases make incompatible API changes. 0.y.z is initial development: anything may change, and the public API should not be treated as stable. Pre-release labels such as 2.0.0-rc.1 have lower precedence than the corresponding final version; build metadata after + does not affect precedence.

SemVer describes precedence and a publisher's compatibility promise, not quality, security, or runtime compatibility. It applies to a declared public API; undocumented behavior may still become de facto relied upon. Breaking changes can include type declarations, CLI flags, package export paths, supported Node/browser versions, and configuration formats—not only function signatures.

Ranges are separate

A version number is distinct from a dependency range such as ^1.2.3 or ~1.2.3. The range syntax determines which versions a package manager may select. The meaning of caret ranges has special edge behavior around zero major versions. Exact pins, ranges, and lockfiles serve different policies; none substitutes for testing.

Engineering guidance

Define public API and support policy, automate release notes/version checks, and treat runtime and type-level compatibility as part of API stability. For consumers, review changelogs and test upgrades even for minor/patch releases. Do not assume every dependency follows SemVer correctly.

Interview questions

  1. What changes justify a minor release? Backward-compatible features under a project's SemVer contract.
  2. What does 0.x signal? Initial development with no stable compatibility guarantee under SemVer.
  3. Does build metadata change precedence? No.
  4. Can a type declaration change be breaking? Yes, because it can break consumers at compile time.
  5. Does SemVer guarantee safe upgrades? No; it is a publisher convention, and range selection/quality are separate.

References