Software Release Versioning

A version is a stable name for a specific software release. The name helps people and tools answer three questions: which release is this, how does it relate to other releases, and what upgrade risk does the publisher claim?

The number alone cannot answer those questions. It gains meaning from a versioning policy. A project might use Semantic Versioning to describe compatibility, Calendar Versioning to describe release time, or an ecosystem-specific scheme such as Python's version format. The durable skill is choosing a policy, defining its contract, and applying it consistently.

Versioning is not the same as source control. A Git tag can mark the commit used for a release, but the version can also appear in package metadata, file names, release notes, and deployed service information. Versioning is not deployment either. You can publish version 2.4.0 without deploying it everywhere, and you can deploy the same version to several environments.

Start with the compatibility contract

Semantic Versioning, usually shortened to SemVer, starts with a declared public API. That API is the contract consumers depend on. It may include callable functions, command-line behavior, configuration fields, data formats, network protocols, or other documented behavior.

This boundary matters because "breaking change" is consumer-facing. A large internal rewrite can be compatible. A one-line change to a documented return value can be breaking. You cannot choose a meaningful version bump until you know what the project promises to preserve.

Under SemVer 2.0.0, a normal version has three non-negative integers:

MAJOR.MINOR.PATCH