Semantic versioning: version numbers people can trust
Short answer: If other people or systems depend on something you release, such as an API used by partners, a plugin, a shared component library or an SDK for your app, the version number is a promise about what changed. Semantic versioning uses MAJOR.MINOR.PATCH: bump the patch for backward-compatible fixes, the minor for backward-compatible new features, and the major when you break something. Define what counts as your public interface, never change a released version, keep a simple record of changes, and give people warning before a major release.
Why version numbers matter to customers
Imagine a partner's online store connected to your booking API. You rename a field from "start" to "start_time" and release it as a small update. Their integration breaks overnight and their bookings stop. From their point of view, nothing warned them.
Semantic versioning, documented at semver.org, exists to prevent that. Its introduction describes "dependency hell": the bigger a system grows and the more packages it depends on, the harder it becomes to upgrade safely. Clear version numbers let people judge the risk of an update without reading every line of code.
The rules in plain words
The specification's summary: given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes.
- MINOR version when you add functionality in a backward-compatible manner.
- PATCH version when you make backward-compatible bug fixes.
A few other rules matter in practice:
- Declare a public API first. The specification says the system only works if you declare a public API, through documentation or code, and that it should be clear and precise. Everything outside it can change without a major bump.
- Never change a release. Once a version is released, its contents must not be modified; any change must be a new version. If 2.3.1 had a bug, release 2.3.2.
- Version zero is for early development. Major version zero, 0.y.z, means anything may change at any time and the public API should not be considered stable. Version 1.0.0 defines the public API.
- Pre-release labels such as 2.0.0-beta.1 let people test upcoming versions without mistaking them for stable ones.
What counts as a breaking change
This is where teams slip. For an API or SDK, breaking changes typically include:
- Removing or renaming an endpoint, field, function or option.
- Changing a field's type or format, such as a price from a number to a string.
- Making an optional parameter required.
- Changing default behaviour people rely on, such as sort order or pagination size.
- Tightening validation so previously accepted requests are rejected.
Adding a new optional field, a new endpoint or a new optional parameter is usually a minor change. Fixing a bug so behaviour matches the documentation is a patch, though if many clients relied on the old behaviour, treat it with care and communicate clearly.
Versioning a web API
For HTTP APIs, the major version is often in the URL, such as /v1/ and /v2/, or in a header. Minor and patch changes are deployed in place, because clients do not pin them. That makes it even more important to keep changes within a major version backward compatible.
When a major version is needed:
- Announce it with a timeline.
- Run both versions side by side for a transition period.
- Mark old features as deprecated in documentation and, where possible, in responses.
- Contact clients still using the old version before switching it off.
Keep a record of changes
A version number says how big a change is; a changelog says what it was. Keep a Changelog, a widely used convention, groups changes by type: Added, Changed, Deprecated, Removed, Fixed and Security, with an Unreleased section collecting changes before the next release. Its own example notes the project adheres to Semantic Versioning, and the two fit naturally together.
For developer audiences, link each release's notes from the version number in your documentation, and mark breaking changes clearly.
Automating it
Many teams use commit message conventions or labels on pull requests to decide automatically whether the next release is a patch, minor or major, and to generate release notes. Automation helps consistency, but a person should still confirm that a release labelled minor really contains no breaking change.
Versions for dependencies you use
Semantic versioning also helps in the other direction, when you depend on other people's packages. Package managers let you accept compatible updates automatically, for example any new minor or patch version within the same major, while holding back majors until you have read the release notes. That only works if the package's maintainers follow the rules, so keep a lockfile, run your tests on every update and treat a supposedly minor update that breaks things as a reason to pin that package more tightly.
Apps versus libraries
Customer-facing apps also have version numbers, but their audience is different. App store version numbers mainly help support and users identify builds; customers rarely care about "breaking changes". Use a simple, increasing scheme, and keep strict semantic versioning for things other developers or systems consume: your API, SDKs, plugins and shared packages.
A worked example
Picture a hypothetical Oxford events company that offers a ticketing API to venue partners. Updates were released without version numbers, and twice a renamed field broke a partner's site.
The company documented its public API, moved it to /v1/, and adopted semantic versioning for the API and its JavaScript SDK. Changes are recorded in a changelog under Added, Changed, Deprecated, Removed, Fixed and Security. When a field rename was needed, it went into /v2/ with six months of overlap, deprecation notes in v1 responses and emails to partners. No partner integration broke during the transition.
FAQ
Is a version like 1.10.0 bigger than 1.9.0?
Yes. Each part is a number, so 1.10.0 comes after 1.9.0.
Should we start at 0.1.0 or 1.0.0?
Use 0.y.z while the interface is still settling, and 1.0.0 once others depend on it.
Does every bug fix need a release?
Each release with a fix gets a new patch number. Group small fixes if releasing often is impractical.
If partners or other teams keep getting caught out by your updates, tell us what they integrate with.