--- title: "Understanding Software Versioning" lang: "en" author: "Mohammad Abu Mattar" canonical: https://mkabumattar.com/post/how-version-number-software-works --- ![Blog post image for Understanding Software Versioning - Explore the essentials of software versioning, including semantic versioning, rules, formats, and tools to manage dependencies and releases effectively.](/_astro/hero.DFRD27Ad_ZeUs6F.webp) [Home](/)›[Blog](/blog)›[All Categories](/blog/categories)›[Software Development](/blog/categories/software-development) Blog [Prev in Software DevelopmentGitHub Actions vs. GitLab CI for Monorepos: Which One Wins?](/blog/post/github-actions-vs-gitlab-ci-for-monorepos)[Next in Software DevelopmentLow-Code vs. Custom Code: Let's Talk About Speed and Tech Debt](/blog/post/low-code-vs-custom-code-speed-tech-debt) [Software Development](/blog/categories/software-development)[Versioning](/blog/categories/versioning)[DevOps](/blog/categories/devops)[Best Practices](/blog/categories/best-practices) # Understanding Software Versioning [Mohammad Abu Mattar](/authors/mohammad-abu-mattar)Published: 12 Nov 2022Updated: 09 May 202503 Mins read08 Mins listen [Markdown for AI(opens in a new tab)](/post/how-version-number-software-works/index.md "Open the plain-Markdown version of this page, for pasting into an AI tool") TL;DR Explore the essentials of software versioning, including semantic versioning, rules, formats, and tools to manage dependencies and releases effectively. Series [Software Engineering Craft](/series/software-engineering-craft)1/6 [NextSoftware Engineering Principles Every Developer Should Know](/blog/post/software-engineering-principles-every-developer-should-know) All posts in this series (6) Blog6 1. [Understanding Software VersioningYou are here](/blog/post/how-version-number-software-works) 2. [Software Engineering Principles Every Developer Should Know](/blog/post/software-engineering-principles-every-developer-should-know) 3. [How to Avoid Over-Engineering Your Code?](/blog/post/how-to-avoid-over-engineering-your-code) 4. [Why You Should Not Use Else Statements in Your Code](/blog/post/why-you-should-not-use-else-statements) 5. [Getting Addicted to Coding: Why We Love Programming More Than Sleep](/blog/post/getting-addicted-to-coding) 6. [Low-Code vs. Custom Code: Let's Talk About Speed and Tech Debt](/blog/post/low-code-vs-custom-code-speed-tech-debt) ### Understanding Software Versioning Contents [Introduction](#introduction)[Why versioning matters](#why-versioning-matters)[Semantic Versioning (SemVer) overview](#semantic-versioning-semver-overview)[Versioning order and precedence](#versioning-order-and-precedence)[Versioning format](#versioning-format)[Versioning rules](#versioning-rules)[Versioning types](#versioning-types)[Practical versioning examples](#practical-versioning-examples)[Versioning in practice](#versioning-in-practice)[Dependency management](#dependency-management)[Release management](#release-management)[Versioning tools](#versioning-tools)[Best practices for versioning](#best-practices-for-versioning)[Conclusion](#conclusion)[References](#references) ## [Introduction](#introduction) Software versioning is an important practice in software development that tracks changes and updates to a codebase. It provides a structured way to identify different iterations of a software product, which keeps things clear for developers, users, and stakeholders. However, managing versioning in systems with complex dependencies can be challenging. Overly restrictive dependency specifications may lead to _version lock_ where upgrading a package requires updating all dependent packages. Conversely, overly loose specifications can result in _version promiscuity_, causing compatibility issues with future versions. This guide explores the principles, rules, and tools of software versioning, with a focus on Semantic Versioning (SemVer). ## [Why versioning matters](#why-versioning-matters) Versioning establishes a clear framework for assigning and incrementing version numbers, which keeps things consistent across development teams and projects. It enables: - **Traceability**: Track changes and identify specific versions of a software product. - **Compatibility Management**: Communicate whether updates are backward-compatible or introduce breaking changes. - **Dependency Resolution**: Help package managers resolve compatible versions for dependencies. - **Release Clarity**: Provide users and developers with clear expectations about updates. Versioning is grounded in widely adopted practices used in both open-source and proprietary software. ## [Semantic Versioning (SemVer) overview](#semantic-versioning-semver-overview) Semantic Versioning, or SemVer, is a widely adopted versioning scheme that uses a three-part number format: `MAJOR.MINOR.PATCH`. Each segment has a specific meaning: - **MAJOR**: Incremented for incompatible API changes (e.g., `2.0.0`). - **MINOR**: Incremented for backward-compatible feature additions (e.g., `1.1.0`). - **PATCH**: Incremented for backward-compatible bug fixes (e.g., `1.0.1`). Additional labels can be used for pre-releases (e.g., `1.0.0-alpha`) and build metadata (e.g., `1.0.0+202505091200`). ### [Versioning order and precedence](#versioning-order-and-precedence) Version numbers are compared to determine precedence. For example: - `1.0.0 < 1.1.0 < 1.1.1 < 2.0.0` Pre-release versions have lower precedence than their associated stable release (e.g., `1.0.0-alpha < 1.0.0`). ### [Versioning format](#versioning-format) SemVer follows a standardized format: - **Stable Release**: `MAJOR.MINOR.PATCH` (e.g., `1.0.0`). - **Pre-release**: Appends a hyphen and identifier (e.g., `1.0.0-alpha.1`). - **Build Metadata**: Appends a plus sign and metadata (e.g., `1.0.0+build.123`). ### [Versioning rules](#versioning-rules) SemVer enforces strict rules to maintain consistency: 1. Once a version is released, its contents **must not** change. 2. A `MAJOR` version of `0` (e.g., `0.y.z`) indicates unstable software where anything may change. 3. Incrementing `MAJOR` resets `MINOR` and `PATCH` to `0`. 4. Incrementing `MINOR` resets `PATCH` to `0`. ## [Versioning types](#versioning-types) Version numbers can be categorized as: - **Major**: Breaking changes that require updates to dependent code. - **Minor**: New features that maintain backward compatibility. - **Patch**: Bug fixes that maintain backward compatibility. - **Pre-release**: Early versions for testing (e.g., `1.0.0-beta`). - **Build Metadata**: Additional data like build IDs that don’t affect precedence. ## [Practical versioning examples](#practical-versioning-examples) Here’s how version numbers reflect different types of updates: - `1.0.0`: Initial stable release. - `1.0.1`: Patch release with bug fixes. - `1.1.0`: Minor release with new features. - `2.0.0`: Major release with breaking changes. - `1.0.0-alpha.1`: Pre-release for testing. - `1.0.0+build.202505091200`: Stable release with build metadata. - `1.0.0-beta+exp.sha.5114f85`: Pre-release with build metadata. ## [Versioning in practice](#versioning-in-practice) ### [Dependency management](#dependency-management) Versioning keeps dependency management predictable. Package managers like npm, Composer, and Maven use version constraints to resolve compatible dependencies. For example: - `^1.0.0`: Allows updates to `1.x.x` but not `2.0.0`. - `~1.0.0`: Allows updates to `1.0.x` but not `1.1.0`. ### [Release management](#release-management) Versioning integrates with release workflows: - **Tagging**: Use Git tags (e.g., `v1.0.0`) to mark releases. - **Changelogs**: Document changes using standards like [Keep a Changelog](https://keepachangelog.com/). - **Automation**: Tools like [Semantic Release](https://semantic-release.gitbook.io/) automate version increments based on commit messages. ## [Versioning tools](#versioning-tools) Several tools handle versioning: - **npm**: Manages JavaScript package versions. - **Composer**: Handles PHP dependencies. - **Maven**: Manages Java project versions. - **Cargo**: Rust’s package manager. - **Python Packaging**: Supports Python version specifiers. - **Git Tags**: Marks specific commits as releases. ## [Best practices for versioning](#best-practices-for-versioning) 1. Adopt SemVer for clarity and consistency. 2. Automate version increments with tools like Semantic Release, so there are fewer manual errors. 3. Maintain changelogs so every change is documented. 4. Use alpha and beta versions to gather feedback before a stable release. 5. Document breaking changes clearly whenever you bump the major version. ## [Conclusion](#conclusion) Software versioning, particularly Semantic Versioning, is a core practice in modern software development. It gives everyone a shared, predictable way to track changes and manage dependencies. Understanding versioning rules, formats, and tools makes release processes easier to reason about and keeps dependency chains from breaking unexpectedly. ## [References](#references) - [Semantic Versioning 2.0.0](https://semver.org/) - [NPM - Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning) - [Composer - Versions and Constraints](https://getcomposer.org/doc/articles/versions.md) - [Maven - POM Reference: Versioning](https://maven.apache.org/pom.html#versioning) - [Git Tagging Basics](https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag) - [Python Packaging - Version Specifiers](https://packaging.python.org/en/latest/specifications/version-specifiers/) - [RubyGems - Semantic Versioning](https://guides.rubygems.org/patterns/#semantic-versioning) - [Cargo (Rust) - Version Field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) - [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - [GitLab - Releases](https://docs.gitlab.com/ee/user/project/releases/) - [GitHub - Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) - [Semantic Release](https://semantic-release.gitbook.io/semantic-release/) Was this useful? ## Tags [#Semantic Versioning](/blog/tags/semantic-versioning)[#Software Versioning](/blog/tags/software-versioning)[#Release Management](/blog/tags/release-management)[#Dependency Management](/blog/tags/dependency-management)[#DevOps Practices](/blog/tags/devops-practices)[#Software Engineering](/blog/tags/software-engineering)[#SemVer](/blog/tags/semver)[#Versioning Schemes](/blog/tags/versioning-schemes)[#Package Management](/blog/tags/package-management) ## Share [Facebook](https://facebook.com/sharer/sharer.php?u=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works "Share on Facebook")[Twitter](https://twitter.com/intent/tweet/?text=Understanding%20Software%20Versioning&url=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works "Share on Twitter")[LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works&title=Understanding%20Software%20Versioning&summary=Explore%20the%20essentials%20of%20software%20versioning%2C%20including%20semantic%20versioning%2C%20rules%2C%20formats%2C%20and%20tools%20to%20manage%20dependencies%20and%20releases%20effectively.&source=https://mkabumattar.com "Share on LinkedIn")[WhatsApp](https://wa.me/?text=Understanding%20Software%20Versioning%20https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works "Share on WhatsApp")[Telegram](https://t.me/share/url?url=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works&text=Understanding%20Software%20Versioning "Share on Telegram")[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works&title=Understanding%20Software%20Versioning "Share on Reddit")[Hacker News](http://news.ycombinator.com/submitlink?u=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works&t=Understanding%20Software%20Versioning "Share on Hacker News")[Pinterest](https://pinterest.com/pin/create/button/?url=https%3A%2F%2Fmkabumattar.com%2Fblog%2Fpost%2Fhow-version-number-software-works&media=&description=Explore%20the%20essentials%20of%20software%20versioning%2C%20including%20semantic%20versioning%2C%20rules%2C%20formats%2C%20and%20tools%20to%20manage%20dependencies%20and%20releases%20effectively. "Share on Pinterest")[Email]() ## Comments ## You might also enjoy More posts on similar topics [![Low-Code vs. Custom Code: Let's Talk About Speed and Tech Debt](/_astro/hero.sDsjchdO_2aAGxk.webp)](/blog/post/low-code-vs-custom-code-speed-tech-debt) ## [Low-Code vs. Custom Code: Let's Talk About Speed and Tech Debt](/blog/post/low-code-vs-custom-code-speed-tech-debt) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [Low Code](/blog/categories/low-code) - [Custom Code](/blog/categories/custom-code) - [Technical Debt](/blog/categories/technical-debt) - [Internal Tools](/blog/categories/internal-tools) - [Software Development](/blog/categories/software-development) In the ever-changing world of making software, there's always this big question: how do we build things quickly without creating a mess down the road? That's where "low-code" development comes into pl [#Low Code](/blog/tags/low-code)[#Custom Code](/blog/tags/custom-code)[#Technical Debt](/blog/tags/technical-debt)+6 tags [read more](/blog/post/low-code-vs-custom-code-speed-tech-debt) [![Software Engineering Principles Every Developer Should Know](/_astro/hero.D6DACa0__Z5aYys.webp)](/blog/post/software-engineering-principles-every-developer-should-know) ## [Software Engineering Principles Every Developer Should Know](/blog/post/software-engineering-principles-every-developer-should-know) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [Software Engineering](/blog/categories/software-engineering) - [Programming Principles](/blog/categories/programming-principles) - [Code Quality](/blog/categories/code-quality) - [Best Practices](/blog/categories/best-practices) Some software engineering principles hold up no matter what stack you're using. They guide you toward maintainable, efficient code. Here's a look at why every developer should know them. What is t [#DRY Principle](/blog/tags/dry-principle)[#KISS Principle](/blog/tags/kiss-principle)[#YAGNI Principle](/blog/tags/yagni-principle)+5 tags [read more](/blog/post/software-engineering-principles-every-developer-should-know) [![Getting Addicted to Coding: Why We Love Programming More Than Sleep](/_astro/hero.DkXq96QT_2tnFpb.webp)](/blog/post/getting-addicted-to-coding) ## [Getting Addicted to Coding: Why We Love Programming More Than Sleep](/blog/post/getting-addicted-to-coding) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [Programming](/blog/categories/programming) - [Career Development](/blog/categories/career-development) - [Developer Lifestyle](/blog/categories/developer-lifestyle) - [Mental Health](/blog/categories/mental-health) For a lot of people, coding stops being just a skill and turns into a passion, a lifestyle, and sometimes an obsession. But what makes programming so captivating? Why do some developers lose track of [#Coding Addiction](/blog/tags/coding-addiction)[#Programming Passion](/blog/tags/programming-passion)[#Developer Burnout](/blog/tags/developer-burnout)+5 tags [read more](/blog/post/getting-addicted-to-coding) [![How to Avoid Over-Engineering Your Code?](/_astro/hero.BBuBduRe_ZMrw4V.webp)](/blog/post/how-to-avoid-over-engineering-your-code) ## [How to Avoid Over-Engineering Your Code?](/blog/post/how-to-avoid-over-engineering-your-code) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [Software Engineering](/blog/categories/software-engineering) - [Programming Best Practices](/blog/categories/programming-best-practices) - [Code Quality](/blog/categories/code-quality) - [Project Management](/blog/categories/project-management) Over-engineering is a common mistake in software development. It adds complexity, stretches out development, and leaves you with features nobody asked for. This post covers how to avoid over-engineeri [#Over Engineering](/blog/tags/over-engineering)[#Software Development](/blog/tags/software-development)[#Clean Code](/blog/tags/clean-code)+6 tags [read more](/blog/post/how-to-avoid-over-engineering-your-code) [![Why You Should Not Use Else Statements in Your Code](/_astro/hero.BtqcHltO_2kocMc.webp)](/blog/post/why-you-should-not-use-else-statements) ## [Why You Should Not Use Else Statements in Your Code](/blog/post/why-you-should-not-use-else-statements) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [Software Engineering](/blog/categories/software-engineering) - [Programming Best Practices](/blog/categories/programming-best-practices) - [Code Quality](/blog/categories/code-quality) - [Refactoring](/blog/categories/refactoring) In software engineering, how you structure your code shapes its readability, maintainability, and overall quality. One often-debated topic is the use of else statements. They look straightforward, and [#Guard Clauses](/blog/tags/guard-clauses)[#Else Statements](/blog/tags/else-statements)[#Clean Code](/blog/tags/clean-code)+6 tags [read more](/blog/post/why-you-should-not-use-else-statements) [![What is a CI/CD?](/_astro/hero.ByLLqYEs_180Vvv.webp)](/blog/post/what-is-a-ci-cd) ## [What is a CI/CD?](/blog/post/what-is-a-ci-cd) - [Mohammad Abu Mattar](/authors/mohammad-abu-mattar) - [DevOps](/blog/categories/devops) - [Software Development](/blog/categories/software-development) - [Automation](/blog/categories/automation) - [CI/CD](/blog/categories/cicd) Introduction Continuous Integration and Continuous Delivery are two of the most important concepts in DevOps. This article covers what CI/CD is and how it fits into a software development process. [#Continuous Integration](/blog/tags/continuous-integration)[#Continuous Delivery](/blog/tags/continuous-delivery)[#Continuous Deployment](/blog/tags/continuous-deployment)+7 tags [read more](/blog/post/what-is-a-ci-cd) 6 related posts