Semantic versioning
seh-MAN-tik VER-zhun-ing
A versioning scheme using MAJOR.MINOR.PATCH numbers to communicate the type of changes in each release.
Semantic versioning (SemVer) uses three numbers separated by dots: MAJOR.MINOR.PATCH. Each number tells you something specific. MAJOR means breaking changes that require code updates. MINOR means new features that are backwards compatible. PATCH means bug fixes that do not change the API. Version 2.4.1 means: second major release, fourth feature addition, first bug fix since that feature.
SemVer is the standard for open source packages. When you run npm install or pip install, the package manager uses SemVer to decide which versions are safe to install. If your package.json says "react": "^18.2.0", npm knows it can install 18.2.1 or 18.3.0 (minor and patch updates) but not 19.0.0 (major update). This automated compatibility check only works if maintainers follow SemVer correctly.
The hard part of SemVer is deciding what counts as a breaking change. Removing a function is obviously breaking. But what about changing the default value of an optional parameter? What about fixing a bug that some users depend on? These edge cases cause real debates. The best teams document their versioning policy explicitly so users know what to expect.
Examples
A library maintainer decides on version numbers for a release.
The release includes a new caching feature and a fix for a memory leak. No existing APIs changed. The maintainer bumps from 4.2.3 to 4.3.0: the minor version increases for the new feature, and the patch resets to zero. If the release had removed a deprecated method, it would be 5.0.0 instead.
A broken SemVer promise causes widespread failures.
A popular npm package bumps from 2.1.0 to 2.2.0 (a minor update) but renames a core function. Hundreds of projects that use '^2.1.0' in their package.json automatically install the new version. Their builds break. The maintainer receives 50 GitHub issues in an hour. The fix is to revert, publish 2.2.1, and release the rename as 3.0.0 instead.
A team uses SemVer to manage internal SDK releases.
The mobile SDK team publishes version 1.8.0 with a new analytics method. App teams adopt it on their own schedule because they know minor versions are safe. When the SDK team needs to restructure the initialization flow, they publish 2.0.0 with a migration guide and give app teams a quarter to upgrade. The old 1.x line gets security patches for six more months.
In practice
Read more on the blog
Frequently asked questions
What does the caret (^) and tilde (~) mean in package.json versions?
The caret (^) allows minor and patch updates. '^2.1.0' accepts 2.1.1, 2.2.0, 2.9.9, but not 3.0.0. The tilde (~) allows only patch updates. '~2.1.0' accepts 2.1.1, 2.1.9, but not 2.2.0. The caret is the default in npm and is appropriate when you trust the package maintainer to follow SemVer. The tilde is more conservative and appropriate for packages that have broken SemVer in the past.
What happens before version 1.0.0?
Versions below 1.0.0 are considered unstable. The SemVer spec says anything can change at any time during 0.x development. In practice, many packages use 0.MAJOR.MINOR where the minor version signals breaking changes. For example, going from 0.4.0 to 0.5.0 might include breaking changes. This is why many teams are cautious about depending on pre-1.0 packages in production.
Related terms
The practice of assigning unique version numbers to software releases to track changes over time.
A code change that causes existing functionality or integrations to stop working.
The ability of new software to work with older versions, data, or integrations without breaking them.
A tool that automates installing, updating, and removing software dependencies for a project.
An external library or package that your project requires to function.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.