Open almost any software project and you will find version numbers everywhere: 2.4.1, 0.9.3, 18.0.0. To a newcomer they look like arbitrary labels that go up over time. They are not. Under a convention called semantic versioning — usually shortened to SemVer — each of those three numbers carries a specific meaning, and together they form a promise from the author of the software to everyone who depends on it.
Understanding that promise is one of the most practical pieces of knowledge you can pick up early in a technical career. It explains why some updates are safe to apply automatically and others break your project at three in the morning.
The three numbers
A semantic version has the form MAJOR.MINOR.PATCH.
| Part | Increment when… | Effect on existing users |
|---|---|---|
| MAJOR | You make an incompatible change to the public interface | Existing code may stop working |
| MINOR | You add functionality in a backwards-compatible way | Existing code keeps working; new options available |
| PATCH | You make a backwards-compatible bug fix | Existing code keeps working, and works better |
Two rules follow from this. When you increment a number, every number to its right resets to zero: after 2.4.7, a breaking change produces 3.0.0, not 3.4.7. And these are not decimal numbers — version 1.12.0 is newer than 1.9.0, because 12 is greater than 9. Each position is compared as a separate integer.
What counts as “breaking”
This is where judgement enters. A change is breaking if code that worked against the previous version might stop working — even if the change looks like an improvement.
- Breaking: removing a function, renaming a parameter, adding a required argument, changing a return type, making validation stricter, changing a default value that alters behaviour.
- Not breaking: adding a new function, adding an optional parameter with a sensible default, improving performance, fixing a bug so that documented behaviour finally works.
The awkward case is a bug fix that people depended on. If a function was documented to return an error but silently returned zero, fixing it is technically correct — and it may still break somebody’s code. Careful maintainers document these cases prominently even when the version bump is only a patch.
The special case of zero
A major version of 0 means the project is in initial development and the public interface should not be considered stable. Under version 0.x.y, anything may change at any time.
This is why depending on a 0.x library deserves more caution than the small numbers might suggest. In practice, many projects treat the minor position as the breaking-change slot while in 0.x: a jump from 0.4.0 to 0.5.0 often means what 1.0.0 to 2.0.0 would mean later.
Releasing 1.0.0 is therefore a meaningful act. It is a public statement that the interface is stable enough for others to build on.
Pre-release and build labels
SemVer allows extra information after the three numbers.
- Pre-release identifiers follow a hyphen:
2.0.0-alpha.1,2.0.0-beta.3,2.0.0-rc.1. A pre-release version sorts before the corresponding final release, so2.0.0-rc.1is older than2.0.0. - Build metadata follows a plus sign:
2.0.0+20260819. It is ignored entirely when comparing versions.
The ordering rule for pre-releases is the reason a release candidate never accidentally outranks the stable release it precedes.
Reading dependency ranges
Package managers use SemVer to decide which updates to accept automatically. Two symbols appear constantly in dependency files, and mixing them up causes real confusion.
| Specifier | Meaning | Accepts |
|---|---|---|
1.4.2 | Exactly this version | Only 1.4.2 |
~1.4.2 | Patch updates only | 1.4.3, 1.4.9 — not 1.5.0 |
^1.4.2 | Minor and patch updates | 1.5.0, 1.9.3 — not 2.0.0 |
* | Anything | Any version, including breaking ones |
The caret is the most common default. It says: “give me improvements and fixes, but never a version that could break my code.” That guarantee only holds if the library author follows SemVer honestly — which is the whole point of the convention.
Note the caret’s behaviour differs below 1.0.0: ^0.4.2 typically allows only 0.4.x, reflecting the instability of the zero major version.
Lock files: the missing piece
Ranges describe what is acceptable. A lock file records what was actually installed, down to the exact version of every transitive dependency. Without one, two developers installing the same project a week apart can end up with different code.
The practical rule: commit your lock file for applications, so builds are reproducible. Libraries usually publish ranges instead, so that consuming applications can resolve a single shared version.
Practical habits
- Read the changelog before a major upgrade. The version number tells you that something broke; only the changelog tells you what.
- Update in small steps. Going from
1.2to4.0in one jump means debugging three sets of breaking changes simultaneously. - Apply patch updates promptly. They are low risk and often contain security fixes.
- Be honest in your own versioning. Shipping a breaking change as a patch release is how you lose the trust of everyone downstream.
- Treat pre-releases as pre-releases. Useful for testing, risky in production.
Conclusion
Semantic versioning turns an opaque label into information you can act on. A patch bump means “safe”. A minor bump means “safe, plus something new”. A major bump means “read before you upgrade”. That shared vocabulary is what makes it possible to build on thousands of packages maintained by people you have never met.
If you want to go deeper into version control, dependency management and the rest of the modern development toolchain, Cursa has free courses on developer and IT tools and programming fundamentals that cover these practices in context.
