Version numbers are a language. Done well, they tell you at a glance whether an update is safe to take or likely to break your build. Semantic Versioning — SemVer — is the convention that gives those three numbers a shared, predictable meaning across the software world.
The three numbers
- MAJOR — incremented for incompatible, breaking changes.
- MINOR — incremented when you add functionality in a backward-compatible way.
- PATCH — incremented for backward-compatible bug fixes.
So going from 2.4.1 to 2.5.0 adds features safely, while 2.4.1 to 3.0.0 warns you to expect breaking changes. That single rule lets consumers update with confidence.
Version ranges
Package managers use SemVer to decide which updates to accept automatically. A caret (^1.2.3) typically allows any compatible 1.x version; a tilde (~1.2.3) allows patch updates only. Understanding these ranges explains why a fresh install can pull a newer version than your lockfile and why lockfiles exist to pin exact versions for reproducible builds.
Versioning your own software
If you publish anything others depend on, follow SemVer honestly. The cardinal rule: never make a breaking change without bumping MAJOR. Renaming a function, removing a field, or changing a return type are breaking changes, even if they feel small. Respecting this is what makes your releases trustworthy.
A note on 0.x
Versions below 1.0.0 are special: the API is considered unstable, and anything may change. Reaching 1.0.0 is a signal that you are committing to stability and the SemVer contract from then on.