SemVer — Explained with Examples

SemVer (Semantic Versioning) is a versioning scheme using MAJOR.MINOR.PATCH numbers to communicate compatibility changes in software releases.

Semantic Versioning follows the format MAJOR.MINOR.PATCH. Increment the MAJOR version when you make incompatible API changes, the MINOR version when you add functionality in a backward-compatible manner, and the PATCH version when you make backward-compatible bug fixes. Pre-release labels like -alpha, -beta, or -rc.1 can be appended.

Think of SemVer like a hotel room number. The floor (MAJOR) tells you the general area. The room section (MINOR) tells you the wing. The room number (PATCH) tells you the exact room. If the hotel renumbers floors, everything changes (MAJOR bump). Adding a new room on the same floor is a MINOR change. Fixing a light bulb is a PATCH.

SemVer gives consumers confidence when upgrading dependencies. A PATCH bump should never break your code. A MINOR bump adds new features but keeps existing ones working. A MAJOR bump signals that you must read the changelog before upgrading.

Given version 2.4.1:
- MAJOR = 2 (breaking changes from v1)
- MINOR = 4 (features added since v2.0)
- PATCH = 1 (bug fixes since v2.4)

Next versions:
- Bug fix: 2.4.2
- New feature (backward-compatible): 2.5.0
- Breaking change: 3.0.0

Tools like npm, pip, and Composer use SemVer for dependency resolution. Specifying ^1.2.3 allows MINOR and PATCH updates; ~1.2.3 allows only PATCH updates.

Git, Release, npm, pip

Version Control Overview