Last updated
Semantic Versioning Calculator Examples
The Semantic Versioning Calculator helps developers understand, compare, and work with semantic version numbers (SemVer). SemVer uses a three-part version number — MAJOR.MINOR.PATCH — where each part has a specific meaning. Below are examples of common versioning scenarios.
Version Bump Decision Guide
- PATCH bump (1.2.3 → 1.2.4) — backward-compatible bug fixes only
- MINOR bump (1.2.3 → 1.3.0) — new backward-compatible features added
- MAJOR bump (1.2.3 → 2.0.0) — breaking changes that require users to update their code
Examples of breaking changes that require a MAJOR bump:
- Removing a public function or method
- Changing a function signature (adding required parameters)
- Changing the return type of a function
- Renaming a public class or module
- Changing the behavior of an existing function in a way that breaks existing callers
Version Range Operators (npm)
Caret (^) — allows updates that do not change the leftmost non-zero digit:
^1.2.3 → >=1.2.3 <2.0.0 (allows 1.x.x updates)
^0.2.3 → >=0.2.3 <0.3.0 (allows 0.2.x updates only)
^0.0.3 → >=0.0.3 <0.0.4 (exact version only)
Tilde (~) — allows patch-level updates only:
~1.2.3 → >=1.2.3 <1.3.0 (allows 1.2.x updates)
~1.2 → >=1.2.0 <1.3.0 (allows 1.2.x updates)
~1 → >=1.0.0 <2.0.0 (allows 1.x.x updates)
Explicit ranges:
>=1.0.0 <2.0.0 (any 1.x.x version)
1.0.0 - 2.0.0 (inclusive range)
* (any version)
Version Comparison Examples
Correct numeric ordering (not string ordering):
1.9.0 < 1.10.0 < 1.11.0 ✓ (numeric comparison)
1.9.0 > 1.10.0 ✗ (wrong — string comparison mistake)
Pre-release version ordering:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0
Build metadata does not affect precedence:
1.0.0+build.1 == 1.0.0+build.2 (same precedence, different metadata)
Pre-Release Versions
1.0.0-alpha.1 — early alpha, unstable
1.0.0-beta.1 — feature-complete, may have bugs
1.0.0-rc.1 — release candidate, near-final
1.0.0 — stable release
Using pre-release versions in npm:
# Install a specific pre-release
npm install my-package@1.0.0-beta.1
# Range that includes pre-releases
npm install "my-package@>=1.0.0-alpha <1.0.0"
Version 0.x.x — Unstable API
Versions below 1.0.0 have different semantics. Any version bump can include breaking changes:
0.1.0 → 0.2.0 may include breaking changes (treat like a major bump)
0.1.0 → 0.1.1 bug fixes only (same as patch)
Dependency Conflict Resolution
Finding the intersection of two version ranges:
Package A requires: ^1.2.0 (>=1.2.0 <2.0.0)
Package B requires: ~1.3.0 (>=1.3.0 <1.4.0)
Intersection: >=1.3.0 <1.4.0 ✓ (compatible — use 1.3.x)
Incompatible ranges:
Package A requires: ^1.0.0 (>=1.0.0 <2.0.0)
Package B requires: ^2.0.0 (>=2.0.0 <3.0.0)
Intersection: none ✗ (conflict — cannot satisfy both)
Conventional Commits and Automated Versioning
Tools like semantic-release determine the next version from commit messages:
fix: correct off-by-one error in pagination → PATCH bump
feat: add dark mode support → MINOR bump
feat!: redesign authentication API → MAJOR bump
# Or using footer:
feat: new export format
BREAKING CHANGE: removed legacy CSV export → MAJOR bump
Changelog Entry Templates
## [2.0.0] - 2026-03-17
### Breaking Changes
- Removed `legacyAuth()` function — use `authenticate()` instead
- Changed `getUser()` return type from Array to Object
## [1.3.0] - 2026-02-10
### Added
- Dark mode support via `theme` option
- New `exportPDF()` method
## [1.2.1] - 2026-01-05
### Fixed
- Fixed off-by-one error in pagination
- Corrected timezone handling in date formatter
Automated Version Bump in CI/CD
# Using npm version command
npm version patch # 1.2.3 → 1.2.4
npm version minor # 1.2.3 → 1.3.0
npm version major # 1.2.3 → 2.0.0
# Using semantic-release (reads commit messages)
npx semantic-release