Semantic Versioning: The MAJOR.MINOR.PATCH Contract

WHY IT EXISTS Software development often creates a tangled web of dependencies called "dependency hell." Without a standard way to signal what a new version contains, updating a package is a gamble. You either lock versions and miss bug fixes, or you update freely and risk your application breaking unexpectedly. Semantic Versioning (SemVer) was created to solve this by making version numbers meaningful.

THE MENTAL MODEL Think of a version number as a public contract, not just a counter. The MAJOR.MINOR.PATCH format is a promise to your users about backward compatibility. By looking at which number changed, a developer can immediately understand the potential impact of an update without reading the entire changelog. This trust is what enables automated and safe dependency management.

HOW IT WORKS Given a version number MAJOR.MINOR.PATCH, you increment one part based on the nature of your changes, after you've declared a stable public API (starting at version 1.0.0). First, MAJOR version zero (0.y.z) is for initial development and is considered unstable. Once you release 1.0.0, the rules are:

PATCH (x.y.Z): Increment for backward-compatible bug fixes only. These are internal changes that fix incorrect behavior without altering the public API.

MINOR (x.Y.z): Increment for new, backward-compatible functionality added to the API. When you increment the minor version, the patch version resets to 0.

MAJOR (X.y.z): Increment for any backward-incompatible changes to the public API. This is a breaking change. When you increment the major version, the minor and patch versions reset to 0.

WHEN TO USE IT Use SemVer whenever you publish software that other people or systems will depend on, such as libraries, frameworks, or public APIs. It is the backbone of modern package management ecosystems like npm (JavaScript), Cargo (Rust), and PyPI (Python), allowing developers to specify safe update ranges (e.g., "allow any patch update, but no minor updates").

WHEN NOT TO USE IT For private applications with no external consumers, strict SemVer can be overkill. It's also not designed for consumer-facing applications like a web browser or operating system, where version numbers often follow marketing or time-based schedules (e.g., Chrome 125, Windows 11) rather than API compatibility rules.

ONE CANONICAL EXAMPLE A library is at version 2.1.5. First, the team fixes a security bug without changing any function signatures; the new version is 2.1.6. Second, they add a new, optional method to a class, which is a backward-compatible feature; the new version becomes 2.2.0. Third, they decide to rename an existing, widely-used function to make it clearer. This is a breaking change, so the new version must be 3.0.0.