Semantic Versioning (SemVer)

The Hook (The "Byte-Sized" Intro)

You install a library at v2.3.1. A new version v2.4.0 comes out. Should you worry? No — the MINOR version bumped, meaning new features but backward-compatible. Then v3.0.0 drops. Now you worry — the MAJOR version changed, meaning breaking changes. Semantic Versioning turns version numbers into a promise. Three numbers. Three meanings. Zero ambiguity.

📖 What is Semantic Versioning?

SemVer is a versioning standard using the format MAJOR.MINOR.PATCH where each number communicates a specific type of change.

Conceptual Clarity

The three components:

Component	When to Bump	Meaning	Example
MAJOR	Breaking changes	API incompatible with previous	`1.0.0 → 2.0.0`
MINOR	New features	Backward-compatible additions	`1.0.0 → 1.1.0`
PATCH	Bug fixes	Backward-compatible fixes	`1.0.0 → 1.0.1`

Pre-release and metadata:

Format	Meaning	Example
`MAJOR.MINOR.PATCH`	Stable release	`1.2.3`
`-alpha`, `-beta`, `-rc.1`	Pre-release label	`2.0.0-beta.1`
`+build.123`	Build metadata (ignored in precedence)	`1.0.0+20260213`

Real-Life Analogy

SemVer is like a restaurant menu update:

PATCH = Fixed a typo in the description (no impact on diners)
MINOR = Added new dishes (existing favorites still available)
MAJOR = Changed the entire cuisine (regulars may not find their favorites)

Visual Architecture

flowchart LR VERSION["v2.3.1"] --> MAJOR["2 = MAJOR<br/>Breaking changes"] VERSION --> MINOR["3 = MINOR<br/>New features"] VERSION --> PATCH["1 = PATCH<br/>Bug fixes"] style MAJOR fill:#2d1b1b,stroke:#e94560,color:#e94560 style MINOR fill:#1a1a2e,stroke:#ffd700,color:#ffd700 style PATCH fill:#1b2d1b,stroke:#53d8fb,color:#53d8fb

Why It Matters

Dependency management: Package managers (npm, pip, Maven) use SemVer to resolve compatible versions.
Communication: Version numbers tell users whether an upgrade is safe.
Automation: CI/CD tools auto-bump versions based on commit types.
Industry standard: SemVer is used by virtually all open-source projects.

Code

bash

# ─── Tag a release with SemVer ───
git tag -a v1.0.0 -m "Initial stable release"
git tag -a v1.0.1 -m "Fix login redirect bug"
git tag -a v1.1.0 -m "Add user profile feature"
git tag -a v2.0.0 -m "Redesign API - breaking changes"

# ─── Pre-release tags ───
git tag -a v2.0.0-alpha.1 -m "Alpha: early API preview"
git tag -a v2.0.0-beta.1 -m "Beta: feature complete, testing"
git tag -a v2.0.0-rc.1 -m "Release candidate: final testing"

# ─── Version 0.x.x: development phase ───
git tag -a v0.1.0 -m "Initial development, API may change"
# v0.x.x = anything may change at any time

# ─── Sort tags by SemVer ───
git tag -l --sort=version:refname

SemVer Decision Guide

Change	Bump	Before → After
Fix a crash in login	PATCH	`1.2.0 → 1.2.1`
Add dark mode setting	MINOR	`1.2.1 → 1.3.0`
Rename all API endpoints	MAJOR	`1.3.0 → 2.0.0`
Remove deprecated function	MAJOR	`2.1.3 → 3.0.0`
Internal refactor (no API change)	PATCH	`1.0.0 → 1.0.1`

Key Takeaways

SemVer = MAJOR.MINOR.PATCH — each number has a specific meaning.
Bump MAJOR for breaking changes, MINOR for features, PATCH for fixes.
Pre-release labels (-alpha, -beta, -rc) indicate unstable versions.
v0.x.x means "anything can change" — the API is not yet stable.

Interview Prep

Q: What does each number in Semantic Versioning represent? A: MAJOR indicates breaking/incompatible changes, MINOR indicates new backward-compatible features, and PATCH indicates backward-compatible bug fixes. Together they communicate the nature and risk of an upgrade.
Q: When should you start at v1.0.0? A: When the public API is considered stable. Versions 0.x.x indicate the project is in initial development and the API may change at any time without a MAJOR bump.
Q: How does SemVer help with dependency management? A: Package managers use SemVer ranges (e.g., ^1.2.0 = compatible with 1.x.x) to automatically install compatible updates while avoiding breaking changes. This only works if maintainers follow SemVer correctly.