Find in Knowledge Base
< All Topics

Semantic Versioning (SemVer)

Bygoktugulvan@gmail.com

Description

Edit

Semantic Versioning (SemVer) is the standard “Language” for version numbers.

If your game is version 1.5.2, those three numbers mean something very specific. As a Tech Lead, you must enforce this so your team (and players) know exactly what changed just by looking at the number.

The format is: MAJOR.MINOR.PATCH

1. The Numbers Explained

X.0.0 -> The MAJOR Version

Meaning: “We changed everything. Old stuff might break.”

  • When to change:
    • In Software (APIs): You made a change that breaks backwards compatibility. If a user updates to 2.0, their old code will crash unless they rewrite it.
    • In Games:
      • Leaving “Early Access” (0.9 -> 1.0).
      • A Massive Expansion Pack (DLC) that changes core mechanics.
      • A Save Game Wipe (players lose their progress because the data format changed).

0.X.0 -> The MINOR Version

Meaning: “We added cool new features, but everything else still works.”

  • When to change:
    • In Software: You added a new function JumpHigher(), but Jump() still works fine. It is backwards compatible.
    • In Games:
      • A Content Update (New Levels, New Weapons, New Characters).
      • A Seasonal Update (Season 2, Halloween Event).
      • Save games are safe.

0.0.X -> The PATCH Version

Meaning: “We didn’t add anything new, we just fixed bugs.”

  • When to change:
    • In Software: Internal tweaks to performance or bug fixes. No API changes.
    • In Games:
      • “Fixed a bug where Mario falls through the floor.”
      • “Reduced shotgun damage by 5%.”
      • “Fixed a typo in the menu.”
    • Crucial Rule: A Patch never adds new content. It only repairs existing content.

2. The “Pre-Release” Tags (The 4th Section)

Sometimes 1.0.0 isn’t ready, but you need to give it to testers. You add a hyphen -.

  • Alpha:1.0.0-alpha.1
    • “This is extremely unstable. It might crash your computer. For internal Devs only.”
  • Beta:1.0.0-beta.3
    • “Feature complete, but buggy. For QA and Beta Testers.”
  • Release Candidate (RC):1.0.0-rc.1
    • “We think this is done. Unless a catastrophic bug is found, this exact file will become 1.0.0.”

3. How to Automate This (DevOps)

You should not update these numbers manually by editing a text file. You will forget.

The Tech Lead Strategy:
Use Git Tags.

  1. The Git Workflow:
    • You push code to Git.
    • When you are ready to release, you create a Tag: git tag v1.2.0.
  2. The Automation (UAT/Jenkins):
    • Your build script runs.
    • It asks Git: “What is the latest tag?” (git describe --tags).
    • It gets v1.2.0.
    • It automatically injects that number into the Game’s UI (bottom right corner of the Menu) and the .exe metadata.

4. Special Case: The “Build Number”

Often, games use 4 numbers: 1.5.2.4502

  • MAJOR.MINOR.PATCH.BUILD

What is the Build Number?
This is an internal counter that goes up +1 every time Jenkins builds the game.

  • Why do you need it?
    • You release Patch 1.5.2.
    • A tester finds a crash.
    • You fix it and build again. Technically, it’s still Patch 1.5.2 (you haven’t released it to the public yet).
    • But now you have two 1.5.2 files! How do you tell them apart?
    • You look at the Build Number: “Crash was in 1.5.2.100, fixed in 1.5.2.101.”

5. Why this matters for Save Files

This is the most dangerous part of Game Dev.

Scenario:

  • Player saves game on Version 1.2.0.
  • You update game to Version 1.3.0 (Added a new “Stamina” stat).
  • Player loads save file.
  • Crash! The game looks for “Stamina” in the save file, but the file was created before Stamina existed.

The Fix (Version Checking):
Inside your Save/Load code, you check the SemVer:

codeC++

if (SaveFileVersion < 1.3.0) { // Old save file! Player.Stamina = 100; // Set a default value manually } else { Player.Stamina = SaveFile.ReadStamina(); }

If you don’t track SemVer strictly, you cannot write this migration code, and you will corrupt players’ saves.

Summary

  • Major (1.x.x): Breaking changes (Save Wipe / DLC).
  • Minor (x.1.x): New Features (New Level).
  • Patch (x.x.1): Bug Fixes only.
  • Build (x.x.x.100): Internal counter for tracking specific executables.