Semantic Versioning (SemVer): MAJOR.MINOR.PATCH Explained

SemVer Format & Decision Rules

Given a version number MAJOR.MINOR.PATCH, increment each part based on the nature of the change. Reset lower segments to zero when incrementing a higher one.

# PATCH: backward-compatible bug fix
# Before: 1.4.2  →  After: 1.4.3
function getUserById(id: string): User | null {
  // Fixed: was throwing instead of returning null for missing users
  return db.users.find(u => u.id === id) ?? null;
}

# MINOR: new backward-compatible feature
# Before: 1.4.3  →  After: 1.5.0
function getUserById(id: string, options?: { includeDeleted?: boolean }): User | null {
  // New: optional includeDeleted parameter added
  const query = options?.includeDeleted ? db.users : db.users.where({ deleted: false });
  return query.find(u => u.id === id) ?? null;
}

# MAJOR: breaking change (changed return type)
# Before: 1.5.0  →  After: 2.0.0
async function getUserById(id: string): Promise<User> {
  // Breaking: now async, throws UserNotFoundError instead of returning null
  const user = await db.users.findById(id);
  if (!user) throw new UserNotFoundError(id);
  return user;
}

Pre-Release Versions & Build Metadata

Use pre-release identifiers for software that is not yet stable. Precedence order: alpha < beta < rc < release. Build metadata is ignored during version comparison.

# Pre-release version progression
1.0.0-alpha        # early internal testing
1.0.0-alpha.1      # second alpha build
1.0.0-beta.1       # external testing begins
1.0.0-rc.1         # release candidate — feature freeze
1.0.0              # final release

# Precedence (lower to higher):
# 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
# < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

# Build metadata (IGNORED during comparison)
1.0.0+20241201.sha.abc1234    # date + git SHA
1.0.0+build.42                # CI build number
# 1.0.0+build.42  ==  1.0.0+build.99  (same version, different builds)

Conventional Commits → Version Bump Mapping

Conventional Commits encode the version bump type directly in the commit message. Tools like semantic-release and release-please read these to automate releases entirely.

# MAJOR bump — breaking change (two ways to signal)
feat!: change getUserById to async with error throwing
# OR footer notation:
fix: correct edge case in user lookup

BREAKING CHANGE: getUserById now throws UserNotFoundError instead of returning null

# MINOR bump — new feature
feat: add includeDeleted option to getUserById
feat(api): add batch user lookup endpoint

# PATCH bump — bug fix, performance, refactor
fix: prevent null pointer when user id is empty
perf: cache user lookup results for 5 minutes
refactor: extract user mapper to separate module

# No version bump (ignored by release tools)
docs: update getUserById JSDoc examples
test: add edge case tests for getUserById
chore: upgrade dev dependencies
ci: add caching to GitHub Actions workflow

SemVer vs CalVer Comparison

Changelog Generation Tools

• ✓semantic-release — Fully automated: reads commits, determines version, publishes to npm/GitHub, updates CHANGELOG.md. Zero configuration for projects following Conventional Commits. Best for libraries.
• ✓release-please (Google) — Creates a Release PR that accumulates all changes since the last release. You control when to merge. Supports multi-package monorepos. Best for apps and teams wanting a manual merge gate.
• ✓standard-version — Local CLI that bumps version, updates CHANGELOG.md, and creates a git tag. No CI integration required. Good for teams starting out.
• ✓git-cliff — Rust-based, highly customizable changelog generator. Supports custom templates (Tera syntax) and any commit format. Fast and configurable for non-standard commit styles.