Semantic Versioning: A Contract for Your Code's Evolution

Why it exists

To escape "dependency hell." In large systems, updating packages can be a nightmare. If dependency rules are too tight, you get version lock and can't upgrade. If they're too loose, you get version promiscuity, where you assume compatibility and things break unexpectedly. SemVer provides a clear, predictable path forward.

The mental model

Think of a version number as a public promise about compatibility. MAJOR.MINOR.PATCH isn't just a number; it's a contract. A MAJOR bump says "Warning: This update may break your code." A MINOR bump says "New features, but your old code is safe." A PATCH bump says "Same features, just working better."

How it works

First, you must declare a public API. A version number takes the form X.Y.Z (MAJOR.MINOR.PATCH). You increment the MAJOR version for incompatible API changes, resetting MINOR and PATCH to 0. You increment the MINOR version for backward-compatible new functionality, resetting PATCH to 0. You increment the PATCH version for backward-compatible bug fixes. Pre-release versions (e.g., 1.0.0-beta) can be denoted by appending a hyphen.

When to use it

Use SemVer anytime you release software that other systems or developers depend on. This is essential for public npm packages, internal company libraries, microservices APIs, and design system component libraries. It allows consumers to automate updates safely, for instance by accepting all patch-level changes but requiring manual review for minor or major ones.

When not to use it

SemVer's strict rules don't apply before version 1.0.0. During initial development (versions 0.y.z), the API is considered unstable and anything may change at any time. The public API is not considered stable until the 1.0.0 release. For monolithic applications with no external consumers, its value is diminished.

One canonical example

A component library is at version 2.4.1. To fix a rendering bug that doesn't alter its API, the team releases 2.4.2 (PATCH). To add a new, optional iconPosition prop, they release 2.5.0 (MINOR). To rename an existing prop from label to text, which is a breaking change for anyone using the component, they must release 3.0.0 (MAJOR).