Almost every major package manager mandates or recommends semantic versioning. Cargo for Rust bakes the concept into its package model. NuGet asks package authors to consider SemVer 2.0.0. npm follows the specification and adds range syntax on top of it.
The benefit is not ceremonial. When a version number follows the specification, another developer can look at a change and understand how much of their own code might need attention. That is the whole point: a version number is a promise about compatibility.
Why a good grasp of semver matters
Version numbers appear everywhere: package manifests, release notes, dependency ranges, deployment dashboards. If the number is chosen carelessly, every downstream decision becomes a guess. A good grasp of semver makes releases predictable and makes upgrades safer.
This article avoids treating the specification as a set of arbitrary rules. Each rule exists to protect a specific promise. Once the promise is clear, the rule is easier to remember.
Terminology
Public API
A piece of software has a public API: the part of its surface area that is publicly exposed for programmatic access. For a library, that means its public types and members. For a command line application, it means the commands and options a user can rely on. For a web service, it means the endpoints and payloads in its contract.
Private code
Private code is everything the software does not expose. A library's private classes and methods are private code. A command line application's internal business logic is private code. A web service's repository layer is private code.
Version
A version is a snapshot of a piece of software. A version number is the identifier for that snapshot.
Backward compatible
A version is backward compatible with an earlier version when its public API is equal to, or a superset of, the earlier version's public API. In plain terms, it can substitute for the earlier version without breaking a caller.
A version that only adds public API features is backward compatible with the version before it. A version that removes or changes public API features is not.
Version number
A version number is a string of the form major.minor.patch, optionally followed by pre release identifiers and build metadata. The first three parts are non negative integers. The optional parts are series of dot separated strings.
1.4.2
2.0.0
1.0.0-rc.1
1.0.0+build.5The major number changes when the public API breaks. The minor number changes when public API is added in a backward compatible way. The patch number changes when a backward compatible fix is released.
Initial development
The initial development phase is the period before the public API is stable. The specification gives this phase a clear signal: major version zero.
Semver in this phase
Anything may change at any time during initial development. The public API should not be considered stable. Version numbers take the form 0.y.z.
Rules
- Start at
0.1.0for the first release. - Increment the minor number for changes and additions.
- Increment the patch number for fixes.
- Do not publish
1.0.0until the API is stable enough to promise compatibility.
Rationale
Major version zero is a warning label. It tells consumers that the project is still finding its shape, so they should not build a dependency range that assumes stability. It also gives the maintainers room to correct design mistakes without pretending a break is a minor change.
Pre release
A pre release is a version that is intended to be used before the corresponding production version. It is useful for release candidates, beta programmes and staged rollouts.
Semver in this phase
Pre release versions add identifiers after the patch number. For example, the first release candidate for 1.0.0 might be 1.0.0-rc.1. A pre release has lower precedence than the corresponding production version.
Rules
- Use a dot separated identifier that communicates the intent.
- Increment the identifier when a new pre release is published.
- Do not reuse an identifier for different content.
Notes
Some package managers exclude pre releases from normal dependency ranges by default. That behavior is intentional. A pre release is an invitation to test, not a promise to every consumer.
Production phase
Production begins when the public API is stable and the project is ready to make compatibility promises. That is the moment for 1.0.0.
Semver in this phase
From 1.0.0 onward, the meaning of each number is fixed:
- Major: incompatible changes to the public API.
- Minor: backward compatible additions to the public API.
- Patch: backward compatible fixes that do not change the public API.
Rules
- Increment the major number for a breaking change, then reset minor and patch to zero.
- Increment the minor number for new functionality, then reset patch to zero.
- Increment the patch number for fixes only.
- Publish the reason for a breaking change, not just the new number.
Notes
Internal refactoring is not a reason to bump the major number. If the public API is unchanged, the version should communicate that. Conversely, a small code change that removes a public member is a major change, even if the diff is tiny.
Build metadata
Build metadata is appended after a plus sign, for example 1.0.0+build.5. It identifies a build without changing precedence. Two versions that differ only in build metadata have the same precedence.
Build metadata is useful for traceability. It is not a substitute for a pre release identifier, and it should not be used to signal compatibility.
How Jering applies this
Jering utilities follow the same discipline. A release that changes an invocation signature or removes a public type is a major release. A release that adds an overload is a minor release. A release that fixes an internal bug is a patch release.
Each utility keeps a changelog on this site. The changelog records the version, the date and the nature of the change, so a consumer can connect the number to the work.
Conclusion
Semantic versioning is a compact communication protocol. It works when maintainers treat the public API as a contract and when consumers read the number before they upgrade. The rules are simple. The discipline is the hard part, and it is worth it.