Files
horizon-airdef/docs/versioning.md
T
Ludovic Marie 385abe5f0c docs/versioning.md: the 0.2 numbering, the way over for old installs, the go-day steps
Ludovic decided (2026-10-21) that the next release is 0.2 for both the game and the launcher, with one
clear scheme instead of vYYYY.MM.DD(.N) and launcher-vX.Y.Z. This page is the design the other 0.2
pull requests implement:

- tags vX.Y.Z and launcher@X.Y.Z (launcher-v0.2.0 is taken), on a line in .github/release-line.txt;
  betas stay pre-releases under their final tag; semver pre-release tags reserved for previews;
- one order for every reader: each 0.2 tag above every tag from before;
- how release.yml, launcher.yml and promote.yml map onto it (HORIZON_VERSION, HORIZON_LAUNCHER_TAG);
- what launchers and servers from before 0.2 do with it, and the bridges that move them
  (launcher-v0.17.0, the last dated game release made latest before v0.2.0);
- the orchestrator's steps for the day Ludovic says go, freeze off included.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 02:13:33 +02:00

9.3 KiB

Versioning

How Horizon's releases are numbered from 0.2 on, how that maps onto the release workflows, and how every install made before 0.2 gets there. The workflows themselves are in release-flow.md.

Until 0.2 the game was tagged by date (v2026.10.19.15) and the launcher counted on its own (launcher-v0.16.0). From 0.2 both follow semantic versioning and share one release line: Horizon 0.2.x is the game and the launcher of the 0.2 line.

Tags

Game Launcher
From 0.2 v0.2.0, v0.2.1, … launcher@0.2.0, launcher@0.2.1, …
Before 0.2 v2026.10.19, v2026.10.19.15, … launcher-v0.1.1 … launcher-v0.16.0 (and the bridge, launcher-v0.17.0)
Release title Horizon 0.2.3: <what changed> Horizon launcher 0.2.1
The program says horizon-server 0.2.3, v0.2.3 in crash reports and telemetry horizon-launcher 0.2.1
  • The line (MAJOR.MINOR) is in .github/release-line.txt, one line such as 0.2. Ludovic decides when it moves; moving it is a one-line pull request (0.3), and the new line's first releases (v0.3.0, launcher@0.3.0) go out as soon as it merges. Without the file, the release train keeps the tags from before 0.2. A feature label no longer bumps anything: it only lists the change under New.
  • Patch releases are every release the train makes: the patch after the newest release tagged on the line, game and launcher counted separately (the game releases more often, so v0.2.14 can go with launcher@0.2.3).
  • Betas are not separate tags. As before, every game release is published as a GitHub pre-release (a beta) under its final tag and promoted in place to stable after 6 hours (Channels). v0.2.4 is the same build whether it is still a beta or already stable.
  • Pre-release tags (v0.3.0-rc.1, v0.3.0-beta.2) are semver's and are reserved for a hand-made preview of a new line; the train never makes them. Every reader orders them before their release and after the release before (v0.2.9 < v0.3.0-beta.1 < v0.3.0-rc.1 < v0.3.0).
  • launcher@, not launcher-v: launcher-v0.2.0 and launcher-v0.2.1 were taken long before 0.2, and a launcher from before 0.2 must not mistake a new 0.2.x for an older release (see below).

The order every reader uses

Every 0.2 tag is newer than every tag from before 0.2. Within each:

  • before 0.2: number by number, missing numbers as zero (v2026.10.19 = v2026.10.19.0);
  • from 0.2: semver: major, minor, patch as numbers, then a release after its pre-releases, whose identifiers compare one by one (numbers before words, numbers as numbers, a shorter list first).

A tag is a 0.2 tag when it is v or launcher@ followed by exactly three numbers (and an optional -PRE) with a major below 1000; a date's first number is a year, so v2026.10.21 never is. The rule is written once per language, with the same tests: crates/horizon-server/src/update.rs (newer), launcher/src/backend.rs (release_order), tools/release_train.py (tag_key, also used by tools/release_channels.py) and website/src/versions.js.

The workflows

  • release.yml: tools/release_train.py decide --kind game picks the tag (next_game_tag); the build gets the version without its v in HORIZON_VERSION, so horizon_core::release::VERSION (and --version, the user agents, crash reports and telemetry) say 0.2.3. No version-bump commits: Cargo.toml versions are what builds from source say. The build checks that horizon-server --version and horizon-prepare --version say it.
  • launcher.yml: decide --kind launcher picks launcher@0.2.N; the build gets HORIZON_LAUNCHER_VERSION (0.2.N) and HORIZON_LAUNCHER_TAG (launcher@0.2.N). The tag tells the launcher which line it is on: a release built with only the version (every launcher before 0.2) is a launcher-v one.
  • promote.yml: tools/release_channels.py promotes the newest due beta, never one older than the stable release; with the shared order, v0.2.0 follows the last dated stable release and no dated beta can follow v0.2.0.
  • Notes: a line's first release (X.Y.0) opens with a paragraph saying so; v0.2.0's and launcher@0.2.0's say that releases are numbered from now on, and how a server that says it is up to date takes 0.2.0.
  • A line's first release goes out as soon as the release train runs after the line changes, without waiting for a pull request, but never while RELEASES_PAUSED is set.

Existing installs: the way to 0.2

Installs made before 0.2 run old code that compares tags number by number, so to them v0.2.0 is older than v2026.10.19.15 and launcher 0.2.0 older than 0.16.0. What each one does, and what moves it:

Install What its old code does with 0.2 How it gets there
Launcher 0.16.0 and older, updating itself Looks only at launcher-v tags and takes one above its own version. Never sees launcher@. The bridge: one last launcher-v0.17.0, built with the new code. Old launchers take it as usual; it knows it is a launcher-v release and takes launcher@0.2.0 next. Two updates, both by themselves.
Launcher 0.16.0 and older, installing games Sorts v0.2.0 below every dated release and below the versions it has installed, so it never offers it. Once the launcher has updated itself (above), it offers v0.2.0 like any update. Until then a player can install v0.2.0 by hand on the Versions page (it is listed last).
Launcher that never updates itself (HORIZON_LAUNCHER_NO_SELF_UPDATE, a package) As above, without the bridge. Update the package, or install v0.2.0 by hand.
horizon-server from before the bridge Reads GitHub's latest release and installs it only if its tag compares higher: v0.2.0 never does. --version <tag> skips the comparison. The game bridge: the last dated release, built with the new code, made stable (latest) before v0.2.0 is published. v0.2.0 then spends 6 hours as a beta, so latest stays the bridge for at least that long; a server updated to it takes v0.2.0 by itself. A server that missed it says it is up to date and needs, once, horizon-server update --version v0.2.0 (0.2.0's notes say so).
Servers the launcher hosts (Servers page) Set up from the launcher's installed versions. Follow the launcher.
install.sh, install.ps1 Install latest. Nothing to do.
Crash reports and telemetry of releases before 0.2 Report the folder name (v2026.10.19.15). Unchanged; 0.2 builds report v0.2.x from the built-in version.

No change on the feed side alone could do it: the dated releases can't be hidden (old launchers also compare with the versions they have installed, and latest is a single release), and GitHub's release JSON can't be rewritten. So the bridges are required, and must never be withdrawn or deleted: launcher-v0.17.0 stays the step every old launcher takes, for as long as any is around.

Outside this repository, whatever reads tags must accept vX.Y.Z and launcher@X.Y.Z too: Kira's release posts, the fleet's release-kick and the orchestrator's heartbeat prompts.

The day Ludovic says go

Run by the orchestrator, in this order. Until step 3, nothing is published.

  1. Merge, in order: this page, the horizon-server update order, the launcher order, the release line (train, workflows), the version sources and the website pull requests. Not the switch pull request yet. Wait for main's checks to pass.
  2. Turn the freeze off:
    gh workflow enable release && gh workflow enable launcher && gh workflow enable promote
    gh variable delete RELEASES_PAUSED
    U=$(id -u); launchctl enable gui/$U/dev.fleet.release-kick
    launchctl bootstrap gui/$U ~/Library/LaunchAgents/dev.fleet.release-kick.plist   # on the Mac mini
    
  3. The bridges go out by themselves within about 25 minutes (the pull requests merged during the freeze count): a dated game beta (v2026.10.DD) and launcher-v0.17.0. Check:
    gh release list --limit 5
    gh run list --workflow launcher --limit 1   # its build log shows horizon-launcher 0.17.0
    
  4. Make the game bridge stable now, so servers see it as latest: gh workflow run promote -f tag=v2026.10.DD (add -f force=true only if it has no smoke test).
  5. Mark the switch pull request ready and merge it (.github/release-line.txt = 0.2, and the docs that talk about 0.2). On the next run, about 10 minutes, the train publishes v0.2.0 as a beta and launcher@0.2.0, both "the first release of 0.2", built from the same code as the bridges plus that pull request.
  6. Check the way over from an old launcher, in a scratch folder:
    export HORIZON_LAUNCHER_HOME=$(mktemp -d)
    # with launcher-v0.16.0's binary:  update --check --json  ->  "launcher": "0.17.0"
    # with launcher-v0.17.0's binary:  update --check --json  ->  "launcher": "0.2.0", "horizon": "v0.2.0" (with Beta builds on)
    
    and gh release view v0.2.0 --json assets, horizon-server --version in the Linux server archive.
  7. v0.2.0 becomes stable after 6 hours (or gh workflow run promote -f tag=v0.2.0). From then on everything is automatic again: v0.2.1, launcher@0.2.1, ….
  8. Point Kira, release-kick and the heartbeat prompts at the new tags (outside this repository).