Semantic Versioning
Semantic Versioning
What is semantic versioning?
- Version numbers as major.minor.patch
- Read the type of change from the numbers
- Compatibility management
What semantic versioning really changes is who makes the update decision. Without rules, someone has to read every set of release notes and decide. With rules, a package manager carries out the instruction mechanically: “upgrade automatically up to the minor version, but leave the major version alone.” Notations such as ^1.4.0 in package.json or ~=1.4 in Python are that instruction. The key point is that human checking moves into tool configuration, which is why even projects with 200–300 dependencies can run by having people review only the packages whose major version changed.
The fine print includes exceptions that practitioners often miss. The 0.y.z range gets no protection from the rules, and the official spec states that “anything may change at any time” in 0.x. In effect, the public API is only fixed once you ship 1.0.0. A pre-release tag after a hyphen, as in 1.0.0-beta.2, is treated as a lower version than the final 1.0.0, and build metadata after a plus sign is ignored entirely in comparisons. CalVer, which uses dates as versions, as in Ubuntu 24.04, serves a different purpose, so mixing the two within one organization only adds confusion.
The most common misconception in the field is treating a version number as a guarantee. The number is just a declaration by the party who releases it, not a verified fact. Plenty of libraries slip configuration default changes into patch versions, and even internal teams often hide breaking changes in minor versions because 'bumping the major version annoys other teams.' On top of that, if the lock file isn't committed, the same install command gives different results on a developer's PC and on the production server, and days are lost just finding the cause of an outage.
Seungtae ParkHands-on AX instructor who teaches AI business development and marketing automation by building real systems
John KimInstructor John Kim, CEO of Nanum Consulting and author of “B2B Marketing Design”Written up as a specification (semver.org) by Tom Preston-Werner, co-founder of GitHub, it has become the de facto standard across the open-source ecosystem.
Consider a hypothetical case. Company A, which runs a logistics SaaS with 140 employees, suffered three outages right after deployments in the fourth quarter of last year alone. Tracing the causes, all three started with automatic updates to external libraries, and two of them were “bug fixes” where only the last digit of the version had changed.
- When Kim, the backend lead, went through a month of deployment logs, 47 packages had been upgraded automatically, and the lock file had never even been committed to the repository.
- When the CTO asked, 'Why did the service go down when only the last digit changed?', Senior Manager Kim pulled up the commit showing that the move from auth library 0.9.3 to 0.9.4 had changed the default token expiry from 24 hours to 1 hour.
- The team put a three-line rule at the top of the repository README: pin 0.x packages to an exact version, use caret ranges only for 1.0.0 and above, and always commit the lock file, no exceptions.
- We applied the same standard to our 12 shared internal modules and added a code review checklist item: removing even one API response field means a major version bump. In the first month, the settlement module went from 2.7.0 to 3.0.0.
- Six months later, post-release incidents fell from 3 per quarter to 0, and the time to review a single update PR dropped from an average of 40 minutes to 10.