Version numbers and patch notes

What changed?!

Garden Defense 1.3.0 reaches phones overnight. By breakfast, Discord is busy: "Why are snails slower?" "Where did Classic mode go?" "Is the shop broken, or is that new?"

The update was fine. The message was missing. Players feel every change, and they trust a studio that tells them what changed and why. This lesson is about numbering each release and writing patch notes: the note that tells players what changed.

Three numbers, and labels before release

Our version names use semantic versioning: MAJOR.MINOR.PATCH. A fix raises the last number, new features the middle one, and a huge change the first (the Updates and player feedback lesson walks through it). For a game, "huge" often means old saves need converting, or the game changes shape.

Test builds get a pre-release label: 1.3.0-beta.2 is the second beta, and the rules rank it below 1.3.0. Before 1.0.0, a 0.y.z version means anything may still change. Once a version is released, it never changes: any later fix gets a new number.

Bolt says: Stores also need a build number that goes up with every upload. The Building and signing app releases lesson in Stage 7 explains it.

Changelog vs patch notes

• The changelogA file called CHANGELOG.md in our GitHub repository. Every notable change, newest version first, with dates. For the team, testers and our future selves.
• Patch notesWritten for players and picked from the changelog: only what a player will notice, in plain words.

The Keep a Changelog guide says "changelogs are for humans, not machines", so a dump of commit messages doesn't count. It groups changes as Added, Changed, Deprecated (leaving soon), Removed, Fixed and Security, with an Unreleased section at the top that fills up until release day.

Writing good patch notes

• Group itNew, Changed, Fixed and Known issues, with the biggest news first.
• Player wordsSay what changes for the player: "Snails are 10% slower", not "SNAIL_SPEED 2.0 to 1.8". Give the reason for big balance changes.
• Credit reporters"Thanks to @tabletdan for reporting the shop freeze!" Use community names, never real names, and ask first.
• Known issuesBugs we know about but haven't fixed yet, so players know we're on it.
• Keep exploits quietAn exploit is a bug players can use to cheat. Never explain how it works until the fix is on players' devices, because many players update slowly.

Hotfix notes

A hotfix is a small, urgent update for one serious bug, like a crash on wave 5. Only the PATCH number moves: 1.3.0 becomes 1.3.1. The Launch day lesson in Stage 7 covers how the team ships one.

Hotfix notes are short: what broke, that it's fixed, and a thank-you. 1.3.1: Fixed a crash on wave 5 on some older Android tablets. Sorry, and thanks for the reports! Post a heads-up on Discord as soon as the bug is confirmed, so players know we're on it before the fix arrives.

Warn before big changes

Some changes hurt as a surprise: a nerf (making something weaker, like a favourite plant), removing a mode, or resetting a leaderboard. Tell players before, not after.

• Say what changes, when, and why: "Thorn Bushes win almost every level, so they do 20% less damage in 1.4.0."
• Give time, like two weeks.
• Say what players keep: "Classic mode leaves on 1 December. Your trophies stay."

It's the Deprecated idea from Keep a Changelog: announce that something is leaving before it goes.

Where patch notes go

• SteamPost an event of the type "Small update / Patch notes". It shows in the download window and on the game's news and library pages, without pushing bigger news off the top of the Library. Big updates use "Major update".
• App Store"What's New in This Version": required for every version after the first, up to 4,000 characters. Apple's rules say new features and significant changes must be listed.
• Google PlayThe release notes field has far less room than Apple's, so the biggest change goes first.
• DiscordThe full notes in #announcements, where players can ask questions.
• In the gameA "What's new" panel after an update. For Hyper Shards, a PWA with no store, it's the one place every player sees.

Bolt says: If the game is translated, the patch notes are too. Next: public roadmaps, telling players what is coming before it ships.