What it is: Semantic versioning — often abbreviated “SemVer” — is a widely adopted convention for numbering software versions using three numbers, written as MAJOR.MINOR.PATCH (for example, 2.4.1), where each of the three numbers has a strict, agreed-upon meaning about the kind of change it represents, rather than being an arbitrary count that just goes up.

Why it exists: Anyone who depends on a piece of software — whether it’s a whole application or a small library used inside another program — needs to know, before upgrading, whether the new version is safe to adopt without changes on their end, or whether it might break something they’re relying on. Semantic versioning exists to answer that question directly from the version number itself, without requiring the person to read through detailed release notes just to find out.

Where it’s used: Semantic versioning is the dominant convention across open-source libraries, packages, and many applications, especially anywhere other developers or systems automatically depend on a specific version of your software. GitHub’s Releases feature, covered starting in Chapter 4, is one of the most common places this numbering scheme is actually applied and published.

Practical example: A popular open-source library goes from version 2.3.1 to 2.3.2 — a tiny bug fix, safe to adopt immediately. Later, it goes to 2.4.0 — new functionality was added, but everything that worked before still works exactly the same way. Later still, it jumps to 3.0.0 — a signal that something has changed in a way that could break code written against version 2, and upgrading will likely require some adjustments.

Before semantic versioning became a common standard, projects numbered their releases however they personally preferred — sometimes sequential counters with no particular meaning, sometimes dates, sometimes arbitrary version names. This created a real, practical problem for anyone depending on that software: there was no reliable way to look at a version number and know, without extensive investigation, whether upgrading was safe or risky. Teams either upgraded blindly and sometimes broke their own systems, or avoided upgrading at all out of caution, missing out on genuine bug fixes and improvements.

This problem became especially acute as software increasingly depended on many other pieces of software, each maintained by different, often unrelated teams. Automatically managing dozens or hundreds of these dependencies — deciding which updates were safe to apply automatically and which needed human review — was essentially impossible without some shared, predictable convention everyone agreed to follow.

The core problem semantic versioning solves: how do you let anyone — a human developer or an automated system — reliably judge the safety of upgrading to a new version, just from its number, without needing to read and interpret detailed release notes every single time?

So, reading a version number like 4.2.7 tells a precise story: this is the fourth major line of this software (meaning there have been at least three earlier breaking changes across its history), the second minor feature addition within that major line, and the seventh patch-level bug fix since that minor addition. Someone already comfortable with version 4.2.0 can trust that 4.2.7 is a safe upgrade, while 5.0.0 deserves a closer look before adopting it.

A GitHub Release is a feature that packages together a specific, permanent snapshot of a repository’s code with human-readable notes describing what’s in it, and optionally downloadable files — all associated with one specific point in the project’s history. Underneath, a Release is built on top of a Git tag — a fixed, unmoving label pointing at one exact commit, as covered in a related guide on release branches — with GitHub adding a friendly, browsable interface, release notes, and file attachments on top of that underlying tag.

When a maintainer creates a Release on GitHub, they choose (or create) the tag it’s based on, write or auto-generate notes describing the changes, and publish it. From that point on, anyone visiting the repository can see a clear, organized list of every published version, in order, each with its own notes and downloads.

flowchart LR
    A["Developer merges a change"] --> B["Team classifies the change: patch, minor, or major"]
    B --> C["Next version number is calculated using SemVer rules"]
    C --> D["A Git tag is created with that version number"]
    D --> E["A GitHub Release is created from that tag"]
    E --> F["Release notes and files are published"]
    F --> G["Dependent projects see the new version and decide whether to upgrade"]
    

Step by step, in plain language: first, a developer’s change — a bug fix, a new feature, or a breaking change — is merged into the project. Second, the team (or an automated tool examining the change) classifies what kind of change it was, according to the definitions in Chapter 3. Third, based on that classification, the next version number is calculated by incrementing the correct position — patch, minor, or major — and resetting any lower positions as needed. Fourth, a Git tag is created at that exact commit, named using that calculated version number, commonly with a leading “v,” such as v2.5.0. Fifth, a GitHub Release is created from that tag, and the team writes or auto-generates release notes describing what changed. Finally, that Release is published and becomes visible to anyone watching the repository — including any automated tool managing dependencies elsewhere, which can now see the new version number and, based purely on that number, judge how urgently or cautiously to consider upgrading.

A tag is a low-level Git concept: a fixed, permanent pointer to one exact commit, with no built-in requirement about what it’s named or what information it carries beyond that pointer. A GitHub Release is a higher-level, GitHub-specific feature built on top of a tag, adding a presentable page with notes and downloadable files. A semantic version number is neither of these — it’s simply a naming convention, most commonly applied as the actual text used to name the tag a Release is built from.

Semantic versioning allows an optional extra label appended after the main three numbers, separated by a hyphen, to mark a version as a pre-release — something like 3.0.0-beta.1 or 2.5.0-rc.2 (where “rc” commonly means “release candidate,” a near-final version being tested before the official release). A pre-release version is understood to come before the plain version of the same number — meaning 3.0.0-beta.1 is considered earlier than the eventual, plain 3.0.0.

GitHub’s own Releases feature includes a matching “This is a pre-release” checkbox when publishing, which visually marks that Release as not yet a stable, general recommendation — helping visitors and automated tools alike distinguish a work-in-progress version from a fully finished one, even before looking closely at the version number itself.

Package managers — tools that automatically download and manage the external libraries a project depends on — commonly let a developer specify not just an exact version, but a range, using semantic versioning’s structure directly. A developer might specify “any compatible version starting from 2.3.0,” meaning the tool is allowed to automatically use 2.3.1, 2.4.0, or 2.9.5 — any minor or patch update — but should never automatically jump to 3.0.0 without the developer’s explicit, deliberate approval, since that would represent a potentially breaking change.

Automated dependency-update tools, including GitHub’s own Dependabot (mentioned in a related guide on code scanning), use this exact same logic: they can confidently propose automatic patch and minor updates as generally low-risk, while flagging major-version updates as requiring more careful, deliberate human review — a distinction that’s only possible because semantic versioning gives the tool a reliable, structured signal to reason about in the first place.

The core trade-off to internalize: semantic versioning trades a real, ongoing discipline requirement — carefully and honestly classifying every change — for a hugely valuable, widely trusted communication and automation tool. The system’s entire value collapses the moment maintainers stop applying its rules carefully and consistently.

This is part of why protecting the release process itself — restricting who can publish a Release, requiring review of the underlying tagged commit, and securing the accounts with permission to do so — matters as a genuine security control, not just a project-management nicety. A GitHub Release is, in a real sense, a trust signal that many other systems and people act on automatically, based largely on its version number alone.

It’s also worth knowing that security-fix releases are sometimes deliberately published as patch-level updates specifically so automated tools will pick them up quickly and with minimal friction — reinforcing why maintaining strict discipline around what counts as a “safe, backward-compatible” patch is so important: a security fix genuinely benefits from being trusted and applied fast.

The Changelog-Driven Pattern maintains a running, categorized list of changes (bug fixes, new features, breaking changes) throughout development, making the correct next version number an almost mechanical calculation once it’s time to release, rather than a rushed, last-minute judgment call.

The Automated Classification Pattern uses tooling that requires each contributor to explicitly label their change as a patch, minor, or major change at the time it’s merged — often enforced as part of the pull-request process itself — so the eventual version bump is calculated automatically and consistently, rather than decided informally by whoever happens to publish the release.

Common anti-patterns to avoid: the Version Number as Marketing (jumping to a large major version number to signal a big product moment, unrelated to any actual breaking change, which undermines the number’s real meaning); the Silent Breaking Change described above; and the Inconsistent Tag Naming pattern (mixing SemVer-formatted tags with arbitrary, non-standard ones across the same project’s history, confusing both people and tools trying to interpret the version timeline).

Common mistakes beginners make: incrementing the wrong number out of habit rather than actually judging the change’s real compatibility impact; forgetting that semantic versioning is a convention, not something GitHub enforces automatically; and treating a “small” breaking change as safe to release without a major-version bump, silently violating the trust automated dependency tools place in the number.