What Is Semantic Versioning? MAJOR.MINOR.PATCH
Semantic versioning tells you from the version number alone whether an update can break your app. The rules, and where they fall short.
Semantic versioning, usually shortened to semver, is a way of numbering software releases as MAJOR.MINOR.PATCH, for example 2.4.1, so the number itself tells you what kind of change you are getting. Raise the first number and something may break. Raise the second and features were added without breaking anything. Raise the third and it is a bug fix. If you let an AI agent update your packages, this is how you tell which updates are safe to accept.
The three rules
The official Semantic Versioning specification summarises it like this. Increment:
the MAJOR version when you make incompatible API changes,
the MINOR version when you add functionality in a backward compatible manner,
the PATCH version when you make backward compatible bug fixes.
Here is what that means when you see an update arrive:
Update | Change | Should you worry? |
|---|---|---|
2.4.1 to 2.4.2 | Patch | Rarely. Read the notes, run your tests, accept |
2.4.1 to 2.5.0 | Minor | Low risk. New features, nothing removed |
2.4.1 to 3.0.0 | Major | Yes. Read the migration notes before touching it |
The promise only holds if the package author follows the rules. Semver is a convention, not a guarantee, so tests still matter.
The 0.y.z exception
Version numbers starting with zero are a special case. The specification says major version zero is for initial development, that anything may change at any time, and that the public API should not be considered stable. Its FAQ suggests starting at 0.1.0 and bumping the minor number for each release.
This is the catch for people building with AI. Many new libraries, including the AI SDKs you may depend on, sit at 0.x. A jump from 0.8.0 to 0.9.0 looks like a small minor bump but is allowed to break things. Treat every minor change in a 0.x package like a major one.
Pre-release versions
A hyphen after the patch number marks a pre-release, such as 1.0.0-alpha or 1.0.0-alpha.1. A pre-release sorts lower than the final 1.0.0, and it is a signal that the author does not yet promise stability. Do not ship production code on one unless you have a reason.
How version ranges use it
In a JavaScript package.json, a caret in front of a version, as in ^2.4.1, allows updates that keep the major number the same. That relies entirely on the author following semver. If a library breaks things in a minor release, the range will pull the breakage in on your next install. Pinning exact versions, as discussed in whether to pin an AI model version, trades convenience for predictability.
Where AI agents trip
They often suggest versions from their training data, which may be old. See why your coding agent keeps suggesting old packages.
They may bump a major version to fix a warning and leave the rest of the code unchanged. Ask for the migration notes and a test run before you accept.
Model names carry their own version numbers that do not follow semver, which is a separate topic covered in AI model version numbers, decoded.
A sensible habit is to let patch and minor updates through on a schedule and handle each major update as its own small task. For the wider picture of shipping an app, see the guide to building an app with AI.
Frequently asked questions
What do MAJOR, MINOR and PATCH mean?
MAJOR changes may break compatibility, MINOR adds features without breaking anything, and PATCH fixes bugs without breaking anything.
Is 1.0.0 stable?
By the specification, version 1.0.0 defines the public API, and changes after that follow the rules. Version 0.y.z is treated as unstable development.
What does the caret in package.json mean?
A caret before a version, such as ^2.4.1, allows updates that keep the major number the same, with stricter handling for 0.x versions. It assumes the author follows semantic versioning.
Do AI models use semantic versioning?
Not in any consistent way. Vendors choose names and numbers freely, so a higher number does not tell you what changed.
How did this land?
About the author
Senior Editor, AI & Product
Cecilia leads the Swarmz editorial desk. She has spent a decade turning complex AI and product topics into writing people actually finish, and she owns the blog's quality bar.
