Semantic Versioning (SemVer) - KB

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.

The Git Workflow:
- You push code to Git.
- When you are ready to release, you create a Tag: git tag v1.2.0.
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.