About Semantic Versioning

Semantic Versioning (SemVer) is a versioning scheme that uses a three-part version number: MAJOR.MINOR.PATCH. It provides a standard way to communicate the nature of changes in software releases.

Version Number Format

A semantic version has the format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

• MAJOR: Increment when you make incompatible API changes
• MINOR: Increment when you add functionality in a backward-compatible manner
• PATCH: Increment when you make backward-compatible bug fixes
• PRERELEASE: Optional label for pre-release versions (alpha, beta, rc)
• BUILD: Optional metadata about the build

When to Bump Each Number

Major Version (X.0.0)

Increment the MAJOR version when you make incompatible changes:

• Removing or renaming public API endpoints or methods
• Changing function signatures that break existing code
• Removing deprecated features
• Making any change that requires users to modify their code

Example: 2.3.1 → 3.0.0 (Breaking change: removed old authentication API)

Note: When you bump MAJOR, reset MINOR and PATCH to 0

Minor Version (0.X.0)

Increment the MINOR version when you add functionality in a backward-compatible way:

• Adding new API endpoints or methods
• Adding optional parameters to existing functions
• Adding new features that don't break existing code
• Marking features as deprecated (but still functional)

Example: 1.2.4 → 1.3.0 (New feature: added export to PDF functionality)

Note: When you bump MINOR, reset PATCH to 0

Patch Version (0.0.X)

Increment the PATCH version for backward-compatible bug fixes:

• Fixing bugs without changing the API
• Security patches
• Performance improvements
• Documentation updates
• Internal refactoring

Example: 1.2.3 → 1.2.4 (Bug fix: corrected date parsing error)

Pre-release Versions

Pre-release versions indicate that the version is unstable and might not satisfy the intended compatibility requirements:

• Alpha: 1.0.0-alpha, 1.0.0-alpha.1 (Early testing, many bugs expected)
• Beta: 1.0.0-beta, 1.0.0-beta.2 (Feature complete, testing phase)
• Release Candidate: 1.0.0-rc.1 (Final testing before release)

Pre-release versions have lower precedence than normal versions:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0

Build Metadata

Build metadata can be added after a plus sign and is ignored when determining version precedence:

• 1.0.0+20130313144700 (with timestamp)
• 1.0.0+exp.sha.5114f85 (with git commit hash)
• 1.0.0-beta+exp.sha.5114f85 (pre-release with build metadata)

Note: 1.0.0+build.1 and 1.0.0+build.2 are considered the same version

Special Cases

Version 0.x.x (Initial Development)

Versions starting with 0 indicate initial development. Anything may change at any time:

• 0.1.0 → First working version
• 0.2.0 → Added major features
• 1.0.0 → First stable public API

Version 1.0.0

Version 1.0.0 defines the public API. After this release, version numbers are based on how the public API changes.

Real-World Examples

Example 1: Bug Fix

Current: 2.4.1 → New: 2.4.2

Fixed a null pointer exception in the user profile component.

Example 2: New Feature

Current: 2.4.2 → New: 2.5.0

Added dark mode support. Existing functionality unchanged.

Example 3: Breaking Change

Current: 2.5.0 → New: 3.0.0

Removed deprecated v1 API endpoints. Users must migrate to v2.

Example 4: Pre-release

Current: 2.5.0 → New: 3.0.0-beta.1

Testing version 3.0.0 with early adopters before final release.

Best Practices

• Start with 0.1.0: First development release
• Release 1.0.0 when API is stable: This is your public API commitment
• Document breaking changes: Use CHANGELOG.md to explain what changed
• Use pre-releases for testing: Let users test before final release
• Never reuse version numbers: Once published, a version is immutable
• Automate versioning: Use tools like semantic-release or standard-version
• Tag releases in Git: Create git tags for each version (v1.2.3)

Integration with Conventional Commits

Combine SemVer with Conventional Commits for automatic versioning:

• fix: → Patch version bump (1.0.0 → 1.0.1)
• feat: → Minor version bump (1.0.0 → 1.1.0)
• BREAKING CHANGE: → Major version bump (1.0.0 → 2.0.0)

Related Tools

• Changelog Generator - Generate changelogs for releases
• Commit Message Linter - Validate commit messages
• Git Command Generator - Build Git commands
• JSON Schema Generator - Version your API schemas
• Case Converter - Format version strings