Semantic Versioning: A Three-Part Numbering System

WHY IT EXISTS Software development requires a way to assign unique identifiers to unique states of the software. Without a shared convention, this process can be chaotic, using inconsistent numbers, dates, or letters that make it difficult to track changes or manage dependencies between different software components.

THE MENTAL MODEL Think of Semantic Versioning (SemVer) as a universal language for software versions. It replaces arbitrary naming with a predictable, three-part number (Major.Minor.Patch) that provides a formal structure for both humans and machines to understand.

HOW IT WORKS The core of SemVer is a three-part version number. For example, in 2.5.1, 2 is the Major version, 5 is the Minor version, and 1 is the Patch version. SemVer also allows for optional tags. A hyphen indicates a prerelease tag (e.g., 1.0.0-alpha), while a plus sign indicates build metadata (e.g., 1.0.0+build.456). Some implementations may even add a fourth number to denote a specific build.

WHEN TO USE IT Use SemVer when you need a clear, widely understood scheme for labeling software releases. It is the most common system and provides a consistent foundation for managing software states and dependencies.

WHEN NOT TO USE IT SemVer is not the only option. Some projects use calendar versioning (CalVer), where the version is based on the release date (e.g., 2024.05.10), which is common for products with time-based release schedules. Other historical systems used letters and other characters, which is now less common but demonstrates that not all versioning is semantic.

ONE CANONICAL EXAMPLE While SemVer is a three-part system, it can be extended. Adobe Flash, for instance, was known for using a four-part version number, with the fourth number denoting the software build.