Semantic Versioning

Semantic Versioning
Name	Semantic Versioning
Developer	Tom Preston-Werner
Genre	Software versioning

Semantic Versioning is a versioning specification for software that prescribes a three-part version number to convey compatibility and change intent between releases. It was popularized by Tom Preston-Werner and has influenced release strategies across projects governed by organizations such as GitHub, Apache Software Foundation, and Eclipse Foundation. Implementations and tools from vendors like Red Hat, Google, Microsoft, Amazon Web Services, and communities including npm, Maven, PyPI, RubyGems, and NuGet reflect its principles in package ecosystems and continuous delivery pipelines.

Overview

Semantic Versioning establishes a numeric triple Major.Minor.Patch to signal the scope of changes in a release. Projects that follow the spec aim to make upgrade decisions predictable for maintainers of downstream systems such as Kubernetes, Docker, Debian, Fedora, and Ubuntu. The model interoperates with dependency resolution in package managers like Conda, Cargo, Homebrew, Chocolatey, and Helm, enabling automated tooling from vendors such as GitLab and integrators like Travis CI and CircleCI to enforce compatibility policies.

Versioning Rules

The core rules require incrementing the Major number for incompatible API changes, the Minor number for backward-compatible functionality additions, and the Patch number for backward-compatible bug fixes. This rule set is applied by projects ranging from Linux kernel modules to libraries in ecosystems like React, Angular, Django, Flask, TensorFlow, PyTorch, and NumPy. Pre-release and build metadata annotations can include identifiers used by CI/CD platforms such as Jenkins and Azure DevOps; these are commonly integrated with version control platforms like Bitbucket and SourceForge. Organizations such as OpenJS Foundation and Python Software Foundation publish guidance aligning their package workflows to these rules.

Comparison to Other Schemes

Semantic Versioning is often compared to calendar-based schemes like CalVer used by projects from Ubuntu and companies like Microsoft for some products, and to incremental build numbers used by Semantic Versioning-averse setups such as internal enterprise release tags at IBM or Oracle Corporation. Other schemes include Major.Minor schemes used in legacy projects at Apache Software Foundation projects and epoch-based versions in distributions like Debian. Corporate versioning practices from Red Hat and Canonical may blend semantic principles with long-term support designations, while ecosystems like Android and iOS use their own numbering conventions alongside marketing names.

Adoption and Practices

Adoption spans open source foundations like Linux Foundation, Apache Software Foundation, Eclipse Foundation, and commercial vendors including Red Hat, Google, Microsoft, Amazon Web Services, and IBM. Popular package registries—npm, PyPI, RubyGems, NuGet, Maven Central—provide dependency resolution behaviors that assume semantic semantics. Major projects such as Node.js, Go, Rust, Ruby, and Java ecosystems document best practices for versioning, and platform vendors like Apple Inc. and Google LLC publish compatibility policies that interact with semantic versioning in SDK and API management. Corporations like Spotify, Netflix, Airbnb, Facebook, and Twitter have public posts describing how they adopt or adapt semantic rules in microservice deployments.

Criticisms and Limitations

Critics argue Semantic Versioning's reliance on correct API change classification can be impractical in large codebases maintained by organizations such as Facebook, Google, or Microsoft where refactors and behavioral changes may blur compatibility boundaries. Dependency hell scenarios observed in ecosystems like npm and PyPI arise when transitive constraints conflict despite semantic labels. Some package authors and distributions, including parts of Debian and enterprise packaging teams at Red Hat, prefer alternatives due to ambiguous rules around private APIs, non-programming artifacts, or binary compatibility concerns evident in projects like GLIBC and LLVM. Legal and compliance teams at companies such as SAP SE and Siemens sometimes require stricter provenance and versioning records than semantic labels alone provide.

Implementation and Tooling

Tooling to enforce and automate semantic versioning exists across CI/CD and package ecosystems: linters and release managers such as Semantic Release, changelog generators like Keep a Changelog patterns used by projects on GitHub, and version bump utilities integrated into Travis CI, CircleCI, Jenkins, GitLab CI/CD pipelines. Language-specific tools include npm version, cargo publish, pip, twine, maven-release-plugin, and gradle plugins. Binary/package build systems such as RPM, deb, Flatpak, and Snapcraft incorporate semantic metadata in distribution artifacts, while repository managers like Artifactory and Nexus Repository support policy enforcement for semantic-compatible dependency resolution.

Category:Software versioning