From 385abe5f0c5cde2651872850fcfd7206461812ca Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 22 Oct 2026 01:23:55 +0200 Subject: [PATCH] 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 --- docs/README.md | 1 + docs/versioning.md | 122 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 docs/versioning.md diff --git a/docs/README.md b/docs/README.md index ffe8e3654..1e268b4d7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor - [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods, and [what carries over from Java mods](research/java-mod-compat.md). - [Modpacks](modpacks.md): porting whole packs (ATM10 and smaller): import, inventory, carry-over, an agent per mod with a harness against the Java original, coverage, and how "10x" is measured. - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it. +- [Versioning](versioning.md): how releases are numbered from 0.2 (`v0.2.x`, `launcher@0.2.x`), how installs from before 0.2 get there, and the steps for the day 0.2 ships. - [Resource packs](resource-packs.md): everything a 26.3 resource pack can change, whether Horizon honours it, and the proof. - [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent. - [Benchmark report format](benchmark-report.md): the versioned JSON every benchmark writes (game, launcher, `tools/perf_bench.py`), the local log and, with consent, the upload. diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 000000000..7a5324bc7 --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,122 @@ +# 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: ` | `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 ` 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).