Semantic versioning (SemVer): what it is and how to use it

Semantic versioning (SemVer) is a set of rules that standardizes a software's version numbers in the MAJOR.MINOR.PATCH format. Each part communicates the type of change — a break in compatibility, a new feature or a bug fix — revealing the impact of updating a dependency before you read the changelog.

• What is semantic versioning (SemVer)?
• Why does semantic versioning exist?
• How does the MAJOR.MINOR.PATCH format work?
• What rules does SemVer set for publishing versions?
• What are the Alpha and Beta phases in the release cycle?
• How to apply semantic versioning in Git and GitHub?

What is semantic versioning (SemVer)?

Semantic versioning is a standard that assigns meaning to each number of a software version, in the MAJOR.MINOR.PATCH format (for example, 2.4.1). Instead of an arbitrary number, each digit carries a promise about what changed since the previous release.

The reference specification is SemVer 2.0.0, written by Tom Preston-Werner, co-founder of GitHub, and published at semver.org. It sums up the three core rules like this: increment the MAJOR version on incompatible API (Application Programming Interface) changes, the MINOR when adding features in a compatible way, and the PATCH on compatible bug fixes.

The model is intentionally simple: with three numbers, any developer understands the risk of an update without needing to read the project's full history. It is this clarity that makes SemVer the de facto standard for open source libraries.

Why does semantic versioning exist?

SemVer was born to solve a concrete problem: the so-called dependency hell. It happens when updating a library breaks others that depended on old behaviors, generating cascading version conflicts that freeze an entire project.

If you have ever installed packages, frameworks or software, you noticed the numeric sequence that indicates the current version. That sequence is crucial to understanding changes, improvements and possible incompatibilities. Without a shared convention, each project would number releases its own way, and automated tools would have no way to decide whether an update is safe.

The scale of the problem is enormous. A large-scale NPM study conducted by Pinckney and colleagues (2023) analyzed all versions of all packages in a registry with more than two million libraries and tens of billions of weekly downloads, and concluded that, when SemVer is well applied, security patches reach dependencies quickly in 90.09% of cases (arXiv:2304.00394). The number shows how whole ecosystems rely on this convention to propagate critical fixes.

How does the MAJOR.MINOR.PATCH format work?

The semantic versioning format is divided into three parts, incremented according to the type of change introduced in the public API. The table below summarizes what each increment means in practice:

Notice that, when incrementing a digit, the ones to its right reset to zero: a new MINOR resets PATCH, and a new MAJOR resets MINOR and PATCH.

MAJOR: when it breaks compatibility

The first digit signals changes that make the software incompatible with previous versions — the breaking changes. Renaming a public function, removing a parameter or changing an API's return format are classic examples that require bumping the MAJOR.

MINOR: when it adds features

The second digit refers to new features or improvements that do not affect compatibility. Anyone already using the previous version can update without changing their code; they just gain optional new features.

PATCH: when it fixes bugs

The third digit covers bug fixes and performance improvements that do not change existing features. It is the safest update to apply, and the one package managers usually install automatically.

What rules does SemVer set for publishing versions?

Semantic versioning is not just about numbers and dots: it establishes clear rules so that everyone understands what each version means. Three of them are essential for publishing releases reliably:

1. X.Y.Z structure — every version follows the X.Y.Z format, where X is MAJOR, Y is MINOR and Z is PATCH. The numbers are non-negative integers and must not contain leading zeroes (use 1.2.0, never 1.02.0).
2. Logical increment — versions advance sequentially. You do not jump from 1.0.0 straight to 3.0.0 without passing through 2.0.0; each release increments exactly one digit.
3. Immutability — once published, a version is never changed. According to the official specification, "Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version."

Immutability is what ensures that 1.4.2 always means the same code, on any machine and on any date — the foundation for reproducible builds.

What are the Alpha and Beta phases in the release cycle?

Before reaching a stable release, software usually goes through pre-release phases that SemVer allows marking with a suffix (for example, 1.0.0-alpha or 1.0.0-beta.2). These phases signal that the version is not yet considered ready for production.

Alpha version

The Alpha version is the first tested by development teams and is generally not published to the general public. The focus is to validate stability and hunt down serious bugs before wider exposure.

Beta version

After Alpha comes Beta, the first public version of the software. Here users play a crucial role: they test the product in real scenarios and provide feedback that guides the final adjustments toward the stable 1.0.0 version.

How to apply semantic versioning in Git and GitHub?

In the version-control workflow with Git and GitHub, semantic versioning materializes as tags and releases. That is how a team permanently records which commit corresponds to each published version number. Tools like npm and other package managers read exactly these versions to resolve dependencies.

It is worth reinforcing how the npm documentation summarizes the progression: start at 1.0.0; increment the last digit on fixes, the middle one on new features and the first one on changes that break compatibility (npm Docs).

What are tags and releases?

Git tags represent specific points in the code's history that correspond to a version. Releases are public descriptions of those tags, where you communicate the news, fixes and changes of each version — the changelog that users actually read.

How to create your first tag in Git?

To turn a commit into a publishable version, follow these steps:

1. Open the terminal at the repository root and confirm the desired commit is in the history with git log --oneline.
2. Create an annotated tag with the version number: git tag -a v1.0.0 -m "First stable version".
3. Check that the tag was created correctly with git tag or git show v1.0.0.
4. Push the tag to the remote repository with git push origin v1.0.0 (or git push --tags to push all at once).

After that, on GitHub, just open the tag and publish a release with the version notes — and your library starts speaking the same language as the entire ecosystem.

Conclusion

Adopting semantic versioning is one of the lowest-cost, highest-return decisions a team can make. With three numbers you turn each release into an explicit promise about compatibility, eliminate much of dependency hell and let tools automate updates safely. Here at CodeCrush, the recommendation is simple: start versioning at 1.0.0 on your next project, be rigorous about bumping the MAJOR when you break something, and treat each number as a contract with whoever uses your code.