Semantic Versioning (Semver)

Semantic versioning creates a shared language between package maintainers and consumers, signaling whether updates are safe to adopt without breaking existing code.

Why it matters

• Enables automated dependency updates with confidence about breaking changes.
• Reduces integration friction by clearly communicating API stability.
• Required by most package managers (npm, Cargo, Composer, Go modules) for version resolution.
• Helps teams plan upgrade cycles and assess technical debt.

Key concepts

• MAJOR (X.0.0): Incremented for incompatible API changes that require consumer code modifications.
• MINOR (0.X.0): Incremented for backward-compatible new functionality.
• PATCH (0.0.X): Incremented for backward-compatible bug fixes.
• Pre-release: Suffixes like -alpha, -beta, -rc.1 indicate unstable versions.
• Build metadata: Suffixes like +build.123 for CI identification (ignored in version precedence).

Version ranges

• Caret (^1.2.3): Allows minor and patch updates (>=1.2.3 <2.0.0).
• Tilde (~1.2.3): Allows only patch updates (>=1.2.3 <1.3.0).
• Exact (1.2.3): Pins to specific version.
• Range (>=1.0.0 <2.0.0): Explicit bounds.

Best practices for maintainers

• Start at 0.1.0 during initial development when API is unstable.
• Move to 1.0.0 when your public API is considered stable.
• Document breaking changes clearly in CHANGELOG when bumping major version.
• Use pre-release versions for testing before stable releases.
• Never modify a released version—publish a new version instead.

Best practices for consumers

• Use caret ranges (^) for most dependencies to receive bug fixes and features.
• Pin exact versions for critical dependencies where any change is risky.
• Use lockfiles (package-lock.json, yarn.lock) to ensure reproducible builds.
• Regularly audit and update dependencies, especially for security patches.
• Test thoroughly when upgrading across major versions.

Common pitfalls

• Breaking changes in minor versions ("semver violations") erode ecosystem trust.
• Not bumping major version for subtle breaking changes like behavior modifications.
• Pre-1.0.0 abuse—staying at 0.x forever to avoid committing to stability.