Semantic Versioning: What Each Number Actually Promises
The real contract behind major.minor.patch, why breaking it quietly erodes trust in a package, and what prerelease tags are actually for.
Published April 15, 2026
major.minor.patch looks like a simple counter, but it's actually a promise to everyone depending on the package. Each position means something specific, and the entire reason tools like npm can safely auto-update dependencies is that maintainers, mostly, honor that promise.
What each number is supposed to signal
Patch (the third number) means a backward-compatible bug fix, nothing about the public interface changed, just a fix. Minor (the middle number) means new functionality was added, but nothing existing broke, safe to upgrade without changing your own code. Major (the first number) means something breaking happened, an upgrade might require changes on the consuming end.
Why a "minor" release that breaks something erodes trust
The entire value of semver is that consumers can set a version range (like ^1.2.0, meaning "any 1.x.x version") and trust automated updates within that range won't break their code. A minor or patch release that actually introduces a breaking change violates that contract silently, someone's automated dependency update breaks production, and the root cause traces back to a version bump that lied about what kind of change it was.
What prerelease tags are actually for
A tag like 1.0.0-alpha or 1.0.0-beta.2 marks a version as not yet stable, explicitly ranking below the eventual 1.0.0 release in comparison. It's how a maintainer can publish and test an in-progress version without it being picked up by consumers expecting a stable release, since most tools default to ignoring prerelease versions unless explicitly requested.