Semantic Versioning Bump Calculator – What’s My Next Version?

Semantic Versioning (SemVer) 2.0.0 is a versioning scheme for software that uses a three-part version number: MAJOR.MINOR.PATCH. It communicates the nature of changes in each release:

• MAJOR — incremented when you make incompatible API changes (breaking changes)
• MINOR — incremented when you add functionality in a backward-compatible manner
• PATCH — incremented when you make backward-compatible bug fixes

Additional labels for pre-release (e.g., -alpha.1, -beta.2, -rc.1) and build metadata (e.g., +build.123) can be appended. Pre-release versions have lower precedence than the associated normal version.

Read the full spec at semver.org

Bump the MAJOR version when you introduce breaking changes — modifications that are not backward-compatible with previous versions. Examples include:

• Removing or renaming public API methods, classes, or endpoints
• Changing the behavior of existing functionality in a way that breaks existing consumers
• Modifying required parameters or return types
• Dropping support for a platform, language version, or dependency
• Changing data formats or database schemas in non-migratable ways

When you bump MAJOR, reset MINOR and PATCH to 0. Example: 2.7.4 → 3.0.0.

Bump the MINOR version when you add new functionality that is backward-compatible. Examples:

• Adding a new API endpoint, method, or class
• Introducing new optional parameters or configuration options
• Adding new features that don't alter existing behavior
• Deprecating existing functionality (but not removing it)
• Substantial new functionality within a private/internal module

When you bump MINOR, reset PATCH to 0. Example: 1.5.3 → 1.6.0.

Bump the PATCH version when you make backward-compatible bug fixes. Examples:

• Fixing a bug that doesn't change the public API
• Performance improvements that don't alter behavior
• Security patches (non-breaking)
• Documentation updates (if versioned with the code)
• Minor internal refactoring with no external impact

PATCH bumps are the most common type of release. Example: 1.2.3 → 1.2.4.

Pre-release versions indicate that a version is unstable and not yet ready for production. They are denoted by a hyphen after the PATCH number, followed by dot-separated identifiers:

• 1.0.0-alpha.1 — Early alpha testing, expect bugs
• 1.0.0-beta.2 — Beta phase, feature-complete but needs testing
• 1.0.0-rc.1 — Release candidate, potentially ready for production
• 2.1.0-preview.3 — Custom pre-release label

Precedence: A pre-release version has lower precedence than the normal version. For example: 1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0.

Use pre-release tags to gather feedback before a stable release. Package managers like npm, pip, and cargo treat pre-releases specially — they are not installed by default unless explicitly requested.

Build metadata is denoted by a plus sign (+) after the PATCH or pre-release identifier. Examples:

• 1.2.3+build.456
• 2.0.0-rc.1+build.789
• 1.0.0+sha.a1b2c3d

Key rule: Build metadata MUST be ignored when determining version precedence. 1.0.0+build.1 and 1.0.0+build.2 are considered the same version for comparison purposes.

Build metadata is useful for tracking CI/CD build numbers, commit SHAs, or build timestamps without affecting version ordering. When bumping a version, build metadata is typically cleared or replaced with a new value.

During initial development (major version 0), the rules are relaxed:

• 0.y.z — Anything may change at any time. The public API is considered unstable.
• In practice, many projects treat 0.MINOR.PATCH similarly: bump MINOR for breaking changes, bump PATCH for fixes.
• 0.1.0 → 0.2.0 may include breaking changes without bumping to 1.0.0.

The first stable release is 1.0.0, signaling that the public API is now stable and SemVer rules apply strictly from that point forward.

No. According to the SemVer 2.0.0 specification, leading zeros are NOT allowed in numeric identifiers. 01.02.03 is invalid.

Valid examples: 1.2.3, 0.10.0, 10.20.30

This rule prevents ambiguity in version comparison — 01 could be misinterpreted as octal or string-sorted differently than 1. Always use plain non-zero-padded integers for MAJOR, MINOR, and PATCH.

While not part of the SemVer spec itself, package managers use version range operators:

• ~1.2.3 (tilde) — Accepts PATCH updates only: >=1.2.3 <1.3.0. Safest option, only bug fixes.
• ^1.2.3 (caret) — Accepts MINOR and PATCH updates: >=1.2.3 <2.0.0. Allows new features but no breaking changes.
• 1.2.x or 1.2.* — Any PATCH version within 1.2.
• * or latest — Any version (use with caution).

Understanding these helps you choose how aggressively to accept dependency updates. Use ~ for maximum stability, ^ for a balance of stability and features.