~ / insights / decoding-software-versioning
2023-05-29 software engineering semver devops git

Decoding Software Versioning: Why SemVer Rules (And What Else Works)

A developer's guide to Semantic Versioning, alternative versioning systems, and why we shouldn't just guess our release numbers.

We have all been there: you download an update for a library you rely on, only for your entire build to break. Software updates should bring joy, not anxiety. That is where Semantic Versioning (SemVer) comes in. It is a simple, structured convention designed to take the guesswork out of software releases by giving meaning to the numbers we use.

At its core, SemVer uses a three-part number system: Major.Minor.Patch (for example, 2.5.1).

  • Major (2): Incremented when you introduce breaking changes that are not backward-compatible.
  • Minor (5): Incremented when you add new features while keeping existing functionality intact.
  • Patch (1): Incremented when you make backward-compatible bug fixes.

Many open-source projects rely on this pattern. It helps everyone on a team understand exactly what they are getting into before they run an update command.

Why Should You Care About SemVer?

Setting up a versioning system might feel like extra homework, but it pays off quickly.

  • No more guessing games: Instead of writing long explanations, your version number itself tells developers if an update is safe to install automatically.
  • Fewer broken builds: By signaling when a change is “breaking” (via a Major bump), you stop package managers from pulling in updates that might crash your production environment.
  • Smoother dependency management: When your downstream libraries play by the rules, keeping your tech stack updated becomes a routine task rather than a stressful event.

How It Works in Practice

Using SemVer means committing to a simple set of rules every time you prepare a release.

1. Major Versions (Breaking Changes)

If you rewrite an API endpoint or remove an old database driver, you must bump the first number.

  • Example: Moving from 1.8.2 to 2.0.0.

2. Minor Versions (New Features)

When you add a cool new search bar or export function that does not ruin any existing integrations, you bump the middle number and reset the patch to zero.

  • Example: Moving from 1.8.2 to 1.9.0.

3. Patch Versions (Bug Fixes)

When you fix a typo, close a security vulnerability, or clean up internal logic without changing how users interact with the tool, you bump the last digit.

  • Example: Moving from 1.8.2 to 1.8.3.

Real-World Examples and Pre-Releases

Version numbers can also convey state before a final release is ready:

  • 1.2.3 – A stable, ready-to-use production release.
  • 2.0.0 – A major evolution of the tool that likely requires code changes on the user’s end.
  • 1.2.4-beta.1 – A pre-release version. It is out in the wild for testing, but expect some rough edges.
  • 1.2.4-rc.1 – A Release Candidate. It is essentially finished, and unless a major bug pops up, this will become the next stable patch.

Admittedly, getting this right takes practice. I am actually still learning how to use SemVer efficiently in my own workflow. If you want to see how I am experimenting with it (or just want to check out my code), take a look at my project here: horus on GitHub.

Other Ways to Version Your Code

While SemVer is highly popular, it is not the only option. Depending on what you are building, one of these alternatives might make more sense:

1. Calendar Versioning (CalVer)

  • Format: YY.MM.MICRO (e.g., 26.04.1 for a release in April 2026).
  • How it works: Numbers mirror the actual release date instead of the structural changes in the code.
  • Best for: Projects with a predictable, time-based release schedule where tracking the age of the software matters most (like Ubuntu or JetBrains IDEs).

2. Sequential / Monotonic Versioning

  • Format: A simple, growing counter like 1, 2, 3... or v105, v106.
  • How it works: Every single deployment simply gets the next number in line.
  • Best for: Internal SaaS apps, hidden APIs, or tools where users are always on the latest version and do not need to manage local upgrades.

3. Codename Versioning

  • Format: Fun, memorable names (like Android’s Vanilla Ice Cream or Ubuntu’s Focal Fossa).
  • How it works: Names are paired with technical version numbers to build a brand identity around major milestones.
  • Best for: Consumer-facing operating systems or massive community projects.

4. ZeroVer (Zero-Based Versioning)

  • Format: Keeps the major version permanently at zero (e.g., 0.1.2, 0.5.4).
  • How it works: It acts as a warning sign to users that the project is in early development, highly unstable, and things might break without warning.
  • Best for: Alpha releases, experimental tools, and early-stage side projects.

5. Effort Versioning (EffVer)

  • Format: EFFORT.MAJOR.MINOR.
  • How it works: A relatively new proposal that focuses on the human impact of an update. It tells the user how much effort it will take them to upgrade, rather than focusing purely on technical API changes.

Next Steps

If you want to dive deeper into the official specifications, head over to the official SemVer website.

Which versioning style fits your current project best? Let me know.

Follow me for more, Bye.

arrow_back All Posts