The Meaning of the Dots
SemVer is a versioning standard that dictates exactly how version numbers are assigned and incremented. A version number takes the form MAJOR.MINOR.PATCH — for example, 1.4.2. Each position has a precise, non-negotiable meaning.
1. MAJOR version (The first number):
Increment this when you make incompatible API changes — changes that will break existing users' code if they upgrade without modification.
- Meaning: "If you upgrade to this version, your existing code may stop working. You will need to update how you use my library."
- Examples: Removing a function, renaming a required parameter, changing a return type, dropping support for an older protocol.
2. MINOR version (The middle number):
Increment this when you add new functionality in a backward-compatible manner.
- Meaning: "There are new features available. All your existing code will continue to work exactly as before — you don't have to change anything."
- Examples: Adding a new optional parameter, adding a new API endpoint, introducing a new helper method.
3. PATCH version (The last number):
Increment this when you make backward-compatible bug fixes.
- Meaning: "A bug was fixed. No features changed, no interfaces changed. It is safe to upgrade."
- Examples: Fixing a crash, correcting an off-by-one error, patching a security vulnerability that doesn't change the API surface.
The Golden Rule:
When you increment a higher-level number, you reset all lower-level numbers to zero.
1.0.0 → fix a bug → 1.0.1
1.0.1 → add a feature → 1.1.0 (PATCH resets to 0)
1.1.0 → breaking change → 2.0.0 (MINOR and PATCH reset to 0)
Pre-release and Build Metadata:
SemVer also supports pre-release labels appended with a hyphen: 1.0.0-alpha, 1.0.0-beta.1, 1.0.0-rc.2. These signal that the release is not yet stable. Build metadata can be appended with a plus sign: 1.0.0+20240101. Build metadata is ignored when determining version precedence — 1.0.0+build.1 and 1.0.0+build.2 are considered equal in terms of precedence.
Version 0.x.x — The Wild West:
A MAJOR version of 0 (e.g., 0.3.1) is a special case. It signals that the API is still unstable and anything may change at any time. The normal SemVer guarantees do not apply until 1.0.0 is released. This is why you'll often see libraries stay at 0.x.x during early development — it's an explicit signal to consumers: "don't depend on stability yet."
Interviewers often ask: "When should you release a 2.0?" The trap is answering "when there are enough new features." The correct answer is: only when you introduce a breaking change — a change that requires existing users to modify their code to upgrade. A rewrite with no API changes is still a MINOR or PATCH release. A single removed function is a MAJOR release. SemVer is about the impact on consumers, not the size of the internal change.