385abe5f0c
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>
123 lines
9.3 KiB
Markdown
123 lines
9.3 KiB
Markdown
# 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](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](https://semver.org) 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](release-flow.md#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:
|
|
```sh
|
|
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:
|
|
```sh
|
|
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:
|
|
```sh
|
|
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).
|