Semantic Versioning

                MAJOR.MINOR.PATCH — e.g. 2.3.1
              

Purpose

Semantic versioning (semver) is a convention for version numbers — MAJOR.MINOR.PATCH — that promises what kind of change a release contains, letting consumers judge upgrade safety from the version number alone.

The three segments

• Major (2.3.1 → 3.0.0): a breaking change — something an existing consumer relies on now behaves differently or no longer exists.
• Minor (2.3.1 → 2.4.0): a backward-compatible new feature — nothing existing breaks.
• Patch (2.3.1 → 2.3.2): a backward-compatible bug fix — behavior moves closer to what was documented, nothing new added.

^2.3.1 (a common dependency range, recall package.json and package-lock.json) matches any release considered compatible under this convention — any 2.x.x at or above 2.3.1, but never 3.0.0.

Behavior notes

• The promise is about observable behavior for consumers, not implementation effort — a small internal change (renaming an exported function, changing a default value) can still be a breaking change if it affects what existing callers depend on.
• Semver applies to a package’s declared public surface (its exports) — internal refactoring of anything not exported requires no version-bump discipline at all, since consumers can’t depend on it.
• A pre-1.0.0 version (0.x.y) is conventionally treated as unstable — any change, including a minor bump, may be breaking, by common (though not universal) convention.

Common mistakes

• Shipping a breaking change as a patch or minor release because the change “feels small” from the maintainer’s perspective, when it still breaks existing consumers.
• Assuming semver alone guarantees safety — it’s a convention maintainers must deliberately follow, not a mechanism enforced by the package registry.

Runtime notes

A versioning convention, not a language feature — used across the npm ecosystem and well beyond it, independent of any specific runtime.