Skip to main content

Semantic versioning

When you publish a mod, players trust you not to corrupt their saves or break their game. If you change a configuration key name or save file schema and label it "Mod Update v1.1", players will update casually and find their game crashing at launch.

Semantic Versioning (SemVer) is the universal language developers use to communicate the impact of an update before anyone downloads it.

The three numbers: MAJOR.MINOR.PATCH​

A version number is formatted as three integers separated by dots: 1.4.2

  • MAJOR (1.x.x): Incremented when you make breaking changes. The save file format changed without backward migration, a setting was renamed, or minimum dependencies changed (e.g., requiring a newer version of ScriptHookVDotNet).
  • MINOR (x.4.x): Incremented when you add new features in a backward-compatible way. A new vehicle spawner key was added, new gang dialogue was introduced, or a new optional setting was included with safe defaults.
  • PATCH (x.x.2): Incremented when you fix bugs without adding features. A null check was added to prevent a crash, or a typo in a subtitle was fixed.

Real world progression​

Consider the evolution of a bodyguard mod:

  • 1.0.0: Initial public release with a single following bodyguard.
  • 1.0.1: Patch: Fixed a crash when reloading the game while the bodyguard is in combat.
  • 1.1.0: Minor: Added a key to command the bodyguard to hold their position (existing saves unaffected).
  • 1.1.1: Patch: Fixed bodyguard ignoring the hold position when rain starts.
  • 2.0.0: Major: Rewrote the save system to support multi-guard squads. Existing profile.json files from v1 must be deleted or migrated.

Embedding versions in your DLL​

Set the assembly version directly in your Visual Studio project properties or .csproj file:

<PropertyGroup>
  <Version>1.0.0</Version>
  <AssemblyVersion>1.0.0.0</AssemblyVersion>
  <FileVersion>1.0.0.0</FileVersion>
</PropertyGroup>

When players or troubleshooters right-click your .dll in Windows and check Properties -> Details, they will see the exact release number matching your changelog.

In the next lesson, we see how to package your mod into a clean, drag-and-drop zip archive.