From 8aacb487984615009fdb2aba4fe1e8890a2956a3 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Wed, 14 Oct 2026 18:48:29 +0200 Subject: [PATCH] release: automatic game releases after main's green checks release.yml now releases the game by itself: after every green checks run of a push to main, every hour (a release the cooldown held goes out without another merge) and by hand. tools/release_train.py decides from the pull requests merged since the last published game release: a release when one changed what players run and the last release is 3 hours old, at once for a pull request labelled release-now; skip-release pull requests don't count. RELEASES_PAUSED=1 stops it. Tags vYYYY.MM.DD, then .1, .2 the same UTC day. Linux (ubuntu-22.04) and Windows build on GitHub with Cargo caches, macOS on the Mac mini's runner (MAC_RUNNER=macos-latest sends it to GitHub). Each builds horizon-client, horizon-ctl and horizon-prepare (all three named: --bin selects only the named binaries), checks all three exist, checks their libraries, starts each one, packages with xtask and archives; the Mac also runs the game offscreen for 300 frames on a new world with resources prepared from its own Minecraft. The notes: New (label feature), Fixed (the rest), Known issues (docs/known-issues.md). A hand-started run off main, or with dry_run, builds everything and writes the notes but publishes nothing. docs/release-flow.md describes the flow, the labels, pausing and rolling back; the launcher gets a test that a release turned back into a draft is never offered. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 243 ++++++++++++++++++++++----- docs/known-issues.md | 6 + docs/release-flow.md | 115 +++++++++++++ launcher/src/backend.rs | 23 +++ tests/test_release_train.py | 99 +++++++++++ tools/release_train.py | 302 ++++++++++++++++++++++++++++++++++ 6 files changed, 748 insertions(+), 40 deletions(-) create mode 100644 docs/known-issues.md create mode 100644 tests/test_release_train.py create mode 100644 tools/release_train.py diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 88a91ee97..cd2ad5ce0 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,57 +1,220 @@ -name: release builds -# Started by hand: gh workflow run release.yml --ref -# Builds the Windows x64 and Linux x86_64 clients (with horizon-ctl and horizon-prepare) and uploads the playable folders -# as artifacts. -# macOS builds are made on the development machines. Linux is built here, on an older Ubuntu, -# so the binary uses the standard loader and runs on any recent distribution (and on NixOS -# through nix-ld): a build made on NixOS asks for a /nix/store loader no other system has. +name: release +# Automatic game releases (docs/release-flow.md). After every green `checks` run on main, every hour (a release +# held by the cooldown goes out without another merge) and by hand, tools/release_train.py decides: a release +# when a pull request merged since the last one changed what players run and that release is 3 hours old, or at +# once for a pull request labelled release-now. RELEASES_PAUSED=1 (repository variable) stops them. +# Builds Linux (an older Ubuntu, so the binary runs on any recent distribution and on NixOS through nix-ld) and +# Windows on GitHub, macOS on the Mac mini's runner (MAC_RUNNER=macos-latest sends it to GitHub), then +# publishes vYYYY.MM.DD[.N] with notes from the merged pull requests. +# gh workflow run release --ref # dry run: builds and notes, publishes nothing +# gh workflow run release -f dry_run=false -f force=true # on main: release now, whatever the rules say on: + workflow_run: + workflows: [checks] + types: [completed] + branches: [main] + schedule: + - cron: '17 * * * *' workflow_dispatch: + inputs: + dry_run: + description: Build everything and write the notes, but publish nothing + type: boolean + default: true + force: + description: Release even without player-facing changes, within the cooldown or while paused + type: boolean + default: false permissions: contents: read +concurrency: + group: game-release + cancel-in-progress: false jobs: - windows: - runs-on: windows-latest + decide: + if: >- + github.event_name != 'workflow_run' || + (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push') + runs-on: ubuntu-latest + timeout-minutes: 10 + outputs: + release: ${{ steps.decide.outputs.release }} + tag: ${{ steps.decide.outputs.tag }} + head: ${{ steps.decide.outputs.head }} + dry_run: ${{ steps.mode.outputs.dry_run }} steps: - uses: actions/checkout@v4 - - name: Install Rust toolchain - run: rustup toolchain install stable --profile minimal - - name: Build the client - # The C runtime linked in, so the game runs without the Visual C++ redistributable. + with: + fetch-depth: 0 + - id: mode + # A dry run never publishes; a hand-started run off main is always one. + run: echo "dry_run=${{ github.event_name == 'workflow_dispatch' && (inputs.dry_run || github.ref != 'refs/heads/main') }}" >> "$GITHUB_OUTPUT" + - id: decide env: - RUSTFLAGS: -C target-feature=+crt-static - run: cargo +stable build --release --locked -p horizon-client --bin horizon-client --bin horizon-ctl -p horizon-prepare --bin horizon-prepare - - name: Only system DLLs - # Vulkan and the rest are loaded at run time; a linked non-system DLL is a - # "DLL not found" dialog on some players' machines. + GH_TOKEN: ${{ github.token }} + RELEASES_PAUSED: ${{ vars.RELEASES_PAUSED }} + # The commit whose checks just passed; a dry run builds the branch it was started on; otherwise + # main's newest commit with green checks. + HEAD_SHA: ${{ github.event.workflow_run.head_sha || (steps.mode.outputs.dry_run == 'true' && github.sha) || '' }} + FORCE: ${{ inputs.force && 'yes' || '' }} run: | - python tools/check_imports.py target/release/horizon-client.exe - python tools/check_imports.py target/release/horizon-ctl.exe - python tools/check_imports.py target/release/horizon-prepare.exe - - name: Package - run: cargo +stable run --locked -p xtask -- package target/release/horizon-client.exe dist/horizon-windows-x64 - - uses: actions/upload-artifact@v4 - with: - name: horizon-windows-x64 - path: dist/horizon-windows-x64 - linux: - runs-on: ubuntu-22.04 + python3 tools/release_train.py decide --kind game ${HEAD_SHA:+--head "$HEAD_SHA"} ${FORCE:+--force} | tee decision.json + echo "### $(jq -r '.reason' decision.json)" >> "$GITHUB_STEP_SUMMARY" + # A dry run builds whatever the decision, to test the builds. + if [[ "${{ steps.mode.outputs.dry_run }}" == true ]]; then echo "release=true" >> "$GITHUB_OUTPUT"; fi + + build: + needs: decide + if: needs.decide.outputs.release == 'true' + name: build ${{ matrix.name }} + strategy: + fail-fast: false + matrix: + include: + - name: linux + os: ubuntu-22.04 + dir: horizon-linux-x86_64 + asset: horizon-linux-x86_64.tar.gz + - name: windows + os: windows-latest + dir: horizon-windows-x64 + asset: horizon-windows-x64.zip + exe: .exe + # The C runtime linked in, so the game runs without the Visual C++ redistributable. + rustflags: -C target-feature=+crt-static + - name: macos + mac: true + dir: horizon-macos-arm64 + asset: horizon-macos-arm64.zip + runs-on: ${{ matrix.mac && (vars.MAC_RUNNER || 'ludovics-mac-mini') || matrix.os }} + timeout-minutes: 40 + env: + RUSTFLAGS: ${{ matrix.rustflags }} + defaults: + run: + shell: bash steps: - uses: actions/checkout@v4 - - name: Install Rust toolchain - run: rustup toolchain install stable --profile minimal + with: + ref: ${{ needs.decide.outputs.head }} + persist-credentials: false + # On the Mac mini's runner, keep target/ (incremental) and .local/ (the prepared resources). + clean: ${{ runner.environment == 'github-hosted' }} + - uses: dtolnay/rust-toolchain@stable + - uses: Swatinem/rust-cache@v2 + if: runner.environment == 'github-hosted' + with: + shared-key: release-${{ matrix.name }} - name: ALSA and udev headers + if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2-dev libudev-dev - - name: Build the client - run: cargo +stable build --release --locked -p horizon-client --bin horizon-client --bin horizon-ctl -p horizon-prepare --bin horizon-prepare - - name: Standard loader and libraries only + - name: Build the client, horizon-ctl and horizon-prepare + run: cargo build --release --locked -p horizon-client --bin horizon-client --bin horizon-ctl -p horizon-prepare --bin horizon-prepare + - name: Every program the release folder takes was built run: | - python3 tools/check_imports.py target/release/horizon-client - python3 tools/check_imports.py target/release/horizon-ctl - python3 tools/check_imports.py target/release/horizon-prepare + for binary in horizon-client horizon-ctl horizon-prepare; do + test -f "target/release/$binary${{ matrix.exe }}" || { echo "::error::target/release/$binary${{ matrix.exe }} is missing"; exit 1; } + done + - name: Only system libraries + # Windows: no non-system DLL (a "DLL not found" dialog on some players' machines). Linux: the standard + # loader and libraries every desktop distribution has. macOS: only the system's own libraries. + run: | + for binary in horizon-client horizon-ctl horizon-prepare; do + file="target/release/$binary${{ matrix.exe }}" + if [[ "$RUNNER_OS" == macOS ]]; then + others=$(otool -L "$file" | tail -n +2 | awk '{print $1}' | grep -v -E '^(/usr/lib/|/System/Library/)' || true) + [[ -z "$others" ]] || { echo "::error::$binary links $others"; exit 1; } + else + ${{ runner.os == 'Windows' && 'python' || 'python3' }} tools/check_imports.py "$file" + fi + done + - name: Every program starts + run: | + set -euo pipefail + bin=target/release + "$bin/horizon-client${{ matrix.exe }}" --help | grep -q -- '--resources' + "$bin/horizon-ctl${{ matrix.exe }}" --help > /dev/null + "$bin/horizon-prepare${{ matrix.exe }}" --version + "$bin/horizon-prepare${{ matrix.exe }}" --help | grep -q -- '--minecraft-dir' + - name: Tools from the runner + if: runner.environment == 'self-hosted' + run: bash tools/ci/runner-env.sh + - name: Resources prepared from the runner's own Minecraft + if: runner.environment == 'self-hosted' + run: bash tools/ci/vanilla-data.sh + - name: The game runs (offscreen, a new world, 300 frames) + if: runner.environment == 'self-hosted' + run: | + set -euo pipefail + home="$RUNNER_TEMP/horizon-smoke" + rm -rf "$home" && mkdir -p "$home" + version=$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' research-lock.json | head -1) + HORIZON_HOME="$home" HORIZON_NO_AUDIO=1 target/release/horizon-client \ + --resources ".local/horizon-client/$version" --offscreen --render-distance 4 --seed 1 \ + --frames 300 --timeout-seconds 180 --smoke-report "$home/smoke.json" > "$home/client.log" 2>&1 \ + || { tail -40 "$home/client.log"; exit 1; } + python3 - "$home/smoke.json" <<'EOF' + import json, sys + report = json.load(open(sys.argv[1])) + print({key: report.get(key) for key in ("adapter", "presented_frames", "resident_chunks", "error")}) + if report.get("error") is not None or report.get("presented_frames") != 300 or not report.get("resident_chunks"): + sys.exit("the smoke run did not draw a world: " + json.dumps(report)[:2000]) + EOF - name: Package - run: cargo +stable run --locked -p xtask -- package target/release/horizon-client dist/horizon-linux-x86_64 + run: | + set -euo pipefail + cargo run --locked -p xtask -- package "target/release/horizon-client${{ matrix.exe }}" "dist/${{ matrix.dir }}" + cd dist + rm -f "${{ matrix.asset }}" + case "${{ matrix.asset }}" in + *.tar.gz) tar czf "${{ matrix.asset }}" "${{ matrix.dir }}" ;; + *) if [[ "$RUNNER_OS" == Windows ]]; then 7z a -tzip "${{ matrix.asset }}" "${{ matrix.dir }}" > /dev/null + else ditto -c -k --keepParent "${{ matrix.dir }}" "${{ matrix.asset }}"; fi ;; + esac + ls -l "${{ matrix.asset }}" - uses: actions/upload-artifact@v4 with: - name: horizon-linux-x86_64 - path: dist/horizon-linux-x86_64 + name: ${{ matrix.asset }} + path: dist/${{ matrix.asset }} + if-no-files-found: error + retention-days: 7 + + publish: + needs: [decide, build] + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Notes + env: + GH_TOKEN: ${{ github.token }} + run: | + python3 tools/release_train.py notes --kind game --tag "${{ needs.decide.outputs.tag }}" \ + --head "${{ needs.decide.outputs.head }}" --out notes > /dev/null + { echo "## $(cat notes/title.txt)"; echo; cat notes/body.md; } >> "$GITHUB_STEP_SUMMARY" + - uses: actions/download-artifact@v4 + with: + path: dist + merge-multiple: true + - name: Publish ${{ needs.decide.outputs.tag }} + if: needs.decide.outputs.dry_run != 'true' + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ needs.decide.outputs.tag }} + run: | + gh release create "$TAG" --target "${{ needs.decide.outputs.head }}" --title "$(cat notes/title.txt)" \ + --notes-file notes/body.md --latest dist/horizon-linux-x86_64.tar.gz dist/horizon-windows-x64.zip \ + dist/horizon-macos-arm64.zip + - name: Dry run, the release that would be published + if: needs.decide.outputs.dry_run == 'true' + run: | + echo "Would publish ${{ needs.decide.outputs.tag }} at ${{ needs.decide.outputs.head }}: $(cat notes/title.txt)" + ls -l dist + - uses: actions/upload-artifact@v4 + with: + name: release-notes + path: notes/ diff --git a/docs/known-issues.md b/docs/known-issues.md new file mode 100644 index 000000000..2c63f4c03 --- /dev/null +++ b/docs/known-issues.md @@ -0,0 +1,6 @@ +# Known issues + +Every game release lists the bullets below under "Known issues" (tools/release_train.py). Keep them short and +written for players; remove a bullet in the pull request that fixes it. + +- Sprint-jumping has been reported as broken, but we couldn't reproduce it. If it happens to you, describe it in #horizon-bugs on Discord. diff --git a/docs/release-flow.md b/docs/release-flow.md index e46ec7dd3..ac2598fc6 100644 --- a/docs/release-flow.md +++ b/docs/release-flow.md @@ -69,3 +69,118 @@ gh api -X POST repos/ludovic111/horizon/branches/main/protection/required_status A skipped `parity` (a fork without the label, a run started by a label) counts as passed, so requiring it never blocks a fork's pull request; the maintainer decides whether to run it. + +## Game releases + +`.github/workflows/release.yml` releases the game by itself. It starts after every green `checks` run of a push +to main, every hour at :17 (so a release the cooldown held goes out without another merge), and by hand. + +```mermaid +flowchart LR + pr(["pull request"]) --> checks{"verify
parity"} + checks -- green --> automerge["auto-merge
(merge commit)"] + automerge --> main(["main"]) + main --> mainchecks{"checks on main"} + mainchecks -- green --> decide{"decide
tools/release_train.py"} + cron(["every hour :17"]) --> decide + decide -- "player-facing PRs, 3 h since the last release,
or release-now" --> build + decide -- otherwise --> wait(["wait"]) + subgraph build["build, in parallel"] + linux["Linux x86_64
GitHub ubuntu-22.04"] + windows["Windows x64
GitHub windows-latest"] + mac["macOS arm64
Mac mini runner
+ offscreen game run"] + end + build --> publish["publish vYYYY.MM.DD[.N]
notes from the merged PRs"] + publish --> launcher(["launchers install it"]) + publish --> kira(["Kira posts it;
pings only with ### New"]) +``` + +### When it releases + +`tools/release_train.py decide --kind game` looks at the pull requests merged into main (first-parent merge +commits) since the last **published** game release: + +- A pull request counts when it changed what players run: `crates/` (not `examples/`, `tests/`, `benches/`), + `xtask/`, `packaging/`, `Cargo.toml`, `Cargo.lock`, `research-lock.json`, or an exporter `horizon-prepare` + compiles (the `mods/horizon/src/test/java/dev/horizonlab/parity/*.java` files its sources name). Markdown never + counts. +- It releases when at least one pull request counts and the last game release is at least 3 hours old. +- A pull request labelled `release-now` (a crash or a blocker) releases at once, cooldown or not. +- A pull request labelled `skip-release` (work players don't see) doesn't count and isn't listed in the notes. +- One release at a time (concurrency group `game-release`); a run that finds nothing new does nothing. +- A scheduled or hand-started run releases main's newest commit whose `checks` passed; after `checks`, the commit + they passed on. + +### Labels + +| Label | Effect | +| --- | --- | +| `feature` | Listed under **New** (Kira pings the releases role); makes the next launcher release a minor one | +| `release-now` | Releases as soon as main's checks pass, without the cooldown | +| `skip-release` | Doesn't trigger a release and isn't listed in the notes | +| `run-parity` | Runs the parity job once on a fork's pull request | +| `parity-regression` | Opened by the nightly audit for a harness that fails on main | + +Pull requests without `feature` are listed under **Fixed**. Titles are written for players, since they become +the notes. + +### Builds + +| Archive | Runs on | Checks | +| --- | --- | --- | +| `horizon-linux-x86_64.tar.gz` | GitHub `ubuntu-22.04` (an older glibc, so it runs on any recent distribution) | the standard loader and libraries only (`tools/check_imports.py`) | +| `horizon-windows-x64.zip` | GitHub `windows-latest`, C runtime linked in | system DLLs only (`tools/check_imports.py`) | +| `horizon-macos-arm64.zip` | The Mac mini's runner (`vars.MAC_RUNNER=macos-latest` sends it to GitHub) | system libraries only (`otool -L`); a 300-frame offscreen run of a new world with resources prepared from the runner's own Minecraft (`--offscreen --frames 300 --smoke-report`) | + +Each builds `horizon-client`, `horizon-ctl` and `horizon-prepare` in release mode, checks all three exist, starts +each one (`--help`, `--version`), packages the folder with `cargo run -p xtask -- package` and archives it. The +GitHub jobs keep their Cargo caches (`Swatinem/rust-cache`); the Mac mini keeps its `target/`. Only the Mac +runs the game: GitHub's runners have neither a GPU worth the name nor the game files. + +### Notes + +`tools/release_train.py notes` writes them from the same pull requests: + +- the title, `Horizon 2026.10.15.1: `, features first, newest first; +- `### New` (label `feature`) and `### Fixed` (the rest), one line per pull request: its title, its number, the + issues it closes; +- `### Known issues`: the bullets of [docs/known-issues.md](known-issues.md); +- thanks to outside contributors, how to install, the disclaimer. + +Kira posts every published release in #releases and pings the releases role only when the notes have a +`### New` section. + +### Starting one by hand + +```sh +gh workflow run release --ref # dry run: builds everything, writes the notes, publishes nothing +gh workflow run release --ref main -f dry_run=false # the usual decision, now +gh workflow run release --ref main -f dry_run=false -f force=true # release now, whatever the rules (even while paused) +``` + +A hand-started run on any branch but main is always a dry run. The notes are in the run's summary and its +`release-notes` artifact. + +### Pausing + +```sh +gh variable set RELEASES_PAUSED --body 1 # no automatic game or launcher releases +gh variable delete RELEASES_PAUSED # back on; the next hourly run catches up +``` + +While paused, runs still decide and say why in their summary; `force=true` still releases. + +### Rolling back + +A bad release is withdrawn by turning it back into a draft: + +```sh +gh release edit v2026.10.15.1 --draft +``` + +Launchers list only published releases: the previous version becomes the newest one again, launchers that +didn't install the bad one won't, and players who did can pick the previous version in the launcher's version +list (`launcher/src/backend.rs` tests `withdrawn_release_is_never_offered`). The tag stays, so the next release +that day takes the next number, and its notes start from the last *published* release, so they list the +withdrawn release's changes again with the fix. Usually the better way out is forward: revert the pull request, +label the revert `release-now`, and a fixed release is out as soon as main's checks pass. diff --git a/launcher/src/backend.rs b/launcher/src/backend.rs index 4d1a9654c..da84e17c3 100644 --- a/launcher/src/backend.rs +++ b/launcher/src/backend.rs @@ -1537,6 +1537,29 @@ mod tests { assert_eq!(launcher, ["launcher-v9.0.0"]); } + /// Rolling a release back (`gh release edit --draft`, docs/release-flow.md) makes the + /// previous one the newest again: it is what `install latest` and the update check offer. + #[test] + fn withdrawn_release_is_never_offered() { + let asset = ASSET.unwrap_or("horizon-linux-x86_64.tar.gz"); + let list = serde_json::json!([ + {"tag_name": "v2026.10.15.1", "draft": true, "assets": [{"name": asset, "browser_download_url": "bad", "size": 1}]}, + {"tag_name": "v2026.10.15", "assets": [{"name": asset, "browser_download_url": "good", "size": 1}]}, + {"tag_name": "v2026.10.14", "assets": [{"name": asset, "browser_download_url": "old", "size": 1}]}, + ]); + let releases = parse_releases(&list, Some(asset), is_game_tag); + assert!(releases.iter().all(|r| r.tag != "v2026.10.15.1")); + assert_eq!(latest(&releases).map(|r| r.tag.as_str()), Some("v2026.10.15")); + let offered = |installed: &[&str]| { + let installed: Vec = installed.iter().map(|t| t.to_string()).collect(); + horizon_update(&releases, &installed).map(|r| r.tag) + }; + assert_eq!(offered(&["v2026.10.14"]), Some("v2026.10.15".into())); + assert_eq!(offered(&[]), Some("v2026.10.15".into())); + // Who installed the withdrawn one is not told to "update" to an older version. + assert_eq!(offered(&["v2026.10.15.1", "v2026.10.14"]), None); + } + #[test] fn versions_compare_by_number() { assert_eq!(compare_versions("v2026.10.13", "v2026.10.12"), Greater); diff --git a/tests/test_release_train.py b/tests/test_release_train.py new file mode 100644 index 000000000..d69fc0793 --- /dev/null +++ b/tests/test_release_train.py @@ -0,0 +1,99 @@ +import datetime as dt +from pathlib import Path +import tempfile +import unittest + +from tools import release_train as train + +NOW = dt.datetime(2026, 10, 15, 12, 0, tzinfo=dt.timezone.utc) + + +def pr(number, title="Fix a thing", labels=(), paths=("crates/horizon-client/src/game.rs",), issues=(), author="ludovic111"): + return {"number": number, "title": title, "labels": list(labels), "paths": list(paths), "issues": list(issues), + "author": author, "url": f"https://github.com/ludovic111/horizon/pull/{number}"} + + +class ReleaseTrainTests(unittest.TestCase): + def test_player_facing_paths(self): + exporters = {"mods/horizon/src/test/java/dev/horizonlab/parity/VanillaMobDataExporter.java"} + self.assertTrue(train.player_facing("crates/horizon-client/src/game.rs", "game")) + self.assertTrue(train.player_facing("Cargo.lock", "game")) + self.assertTrue(train.player_facing("xtask/src/main.rs", "game")) + self.assertTrue(train.player_facing(next(iter(exporters)), "game", exporters)) + self.assertFalse(train.player_facing("mods/horizon/src/test/java/dev/horizonlab/parity/VanillaFoodOracle.java", "game", exporters)) + self.assertFalse(train.player_facing("crates/horizon-world/examples/probe.rs", "game")) + self.assertFalse(train.player_facing("crates/horizon-client/README.md", "game")) + self.assertFalse(train.player_facing("tools/test_food_parity.py", "game")) + self.assertFalse(train.player_facing("launcher/src/main.rs", "game")) + self.assertTrue(train.player_facing("launcher/src/main.rs", "launcher")) + self.assertTrue(train.player_facing("crates/horizon-prepare/src/lib.rs", "launcher")) + self.assertFalse(train.player_facing("launcher/links.json", "launcher")) + self.assertFalse(train.player_facing("crates/horizon-client/src/game.rs", "launcher")) + + def test_the_exporters_are_those_horizon_prepare_names(self): + found = train.exporters() + self.assertIn(train.EXPORTERS + "VanillaMobDataExporter.java", found) + self.assertTrue(all(path.endswith(".java") for path in found)) + + def test_game_tags_count_up_within_a_day(self): + today = dt.date(2026, 10, 15) + self.assertEqual(train.next_game_tag(["v2026.10.14", "launcher-v0.1.4"], today), "v2026.10.15") + self.assertEqual(train.next_game_tag(["v2026.10.15"], today), "v2026.10.15.1") + self.assertEqual(train.next_game_tag(["v2026.10.15", "v2026.10.15.1", "v2026.10.15.2"], today), "v2026.10.15.3") + + def test_launcher_tags_bump_the_patch_or_the_minor(self): + tags = ["launcher-v0.1.3", "launcher-v0.1.10", "v2026.10.15", "launcher-v0.1.4"] + self.assertEqual(train.next_launcher_tag(tags, minor=False), "launcher-v0.1.11") + self.assertEqual(train.next_launcher_tag(tags, minor=True), "launcher-v0.2.0") + + def test_decision(self): + hour = dt.timedelta(hours=1) + decide = lambda prs, age, **kw: train.decision("game", prs, NOW - age, NOW, **kw)[0] + self.assertTrue(decide([pr(1)], 4 * hour)) + self.assertFalse(decide([pr(1)], 2 * hour), "within the cooldown") + self.assertTrue(decide([pr(1, labels=["release-now"])], 0.1 * hour)) + self.assertFalse(decide([pr(1, paths=[])], 9 * hour), "nothing players run") + self.assertFalse(decide([pr(1, labels=["skip-release"])], 9 * hour)) + self.assertFalse(decide([pr(1, labels=["release-now", "skip-release"])], 9 * hour)) + self.assertFalse(decide([pr(1)], 9 * hour, paused=True)) + self.assertTrue(decide([], 0.1 * hour, paused=True, force=True)) + self.assertTrue(train.decision("game", [pr(1)], None, NOW)[0], "the first release") + + def test_notes(self): + prs = [pr(5, "Nether portals: vanilla timing and linking (fixes #94)", issues=[94]), + pr(6, "Controllers: gilrs input layer and gameplay", labels=["feature"], author="cosmic"), + pr(7, "Release folder in Rust", labels=["skip-release"]), + pr(8, "Website footer", paths=[])] + title, body = train.notes("game", "v2026.10.15.1", prs, ["- Sound cuts out after an hour."]) + self.assertEqual(title, "Horizon 2026.10.15.1: Controllers, nether portals") + self.assertIn("### New\n- Controllers: gilrs input layer and gameplay (#6)", body) + self.assertIn("### Fixed\n- Nether portals: vanilla timing and linking (#5, fixes #94)", body) + self.assertIn("### Known issues\n- Sound cuts out after an hour.", body) + self.assertNotIn("#7", body) + self.assertNotIn("#8", body) + self.assertIn("Thanks to @cosmic.", body) + self.assertLess(body.index("### New"), body.index("### Fixed")) + + def test_a_long_release_is_named_after_its_first_titles(self): + prs = [pr(n, f"Change number {n} with a fairly long title") for n in range(1, 10)] + title, _ = train.notes("game", "v2026.10.15", prs, []) + self.assertTrue(title.startswith("Horizon 2026.10.15: Change number 9"), title) + self.assertTrue(title.endswith("more fixes"), title) + self.assertLess(len(title), 100) + + def test_launcher_notes(self): + title, body = train.notes("launcher", "launcher-v0.2.0", [pr(3, "Launcher: say the self-update succeeded")], []) + self.assertEqual(title, "Horizon launcher 0.2.0") + self.assertIn("### Fixed\n- Launcher: say the self-update succeeded (#3)", body) + self.assertNotIn("Known issues", body) + + def test_known_issues_are_the_bullets_of_the_file(self): + with tempfile.TemporaryDirectory() as temp: + path = Path(temp, "known-issues.md") + path.write_text("# Known issues\n\nSome text.\n\n- One.\n- Two, with **bold**.\n continued\n") + self.assertEqual(train.known_issues(path), ["- One.", "- Two, with **bold**."]) + self.assertEqual(train.known_issues(Path(temp, "missing.md")), []) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/release_train.py b/tools/release_train.py new file mode 100644 index 000000000..511ccac5e --- /dev/null +++ b/tools/release_train.py @@ -0,0 +1,302 @@ +#!/usr/bin/env python3 +"""Decides when Horizon releases, names the release and writes its notes (.github/workflows/release.yml). + + python3 tools/release_train.py decide --kind game [--head SHA] [--force] + python3 tools/release_train.py decide --kind launcher + python3 tools/release_train.py notes --kind game --tag v2026.10.15 --out dist/notes + +A kind releases when a pull request merged into main since its last published release changed one of its +player-facing paths (GAME_PATHS, LAUNCHER_PATHS) and that release is at least COOLDOWN old, or when one of those +pull requests is labelled release-now. Pull requests labelled skip-release (work players don't see) don't count +towards a release and aren't listed in the notes. RELEASES_PAUSED=1 (a repository variable) stops automatic releases. + +Game releases are tagged vYYYY.MM.DD, then .1, .2 the same UTC day; launcher releases launcher-vX.Y.Z, the +patch after the last launcher tag, or the next minor when a merged pull request is labelled feature. Notes: +"### New" lists the pull requests labelled feature, "### Fixed" the others, "### Known issues" the bullets of +docs/known-issues.md. See docs/release-flow.md. + +Prints the decision as JSON and writes it to $GITHUB_OUTPUT when set. Needs git history and the gh CLI. +""" + +import argparse +import datetime as dt +import json +import os +from pathlib import Path +import re +import subprocess +import sys + +ROOT = Path(__file__).resolve().parents[1] +REPO = os.environ.get("GITHUB_REPOSITORY", "ludovic111/horizon") +COOLDOWN = dt.timedelta(hours=3) +EXPORTERS = "mods/horizon/src/test/java/dev/horizonlab/parity/" + +# What players run. Documentation (*.md), tests, benchmarks and harness probes (examples/) never count. +GAME_PATHS = ["crates/", "xtask/", "packaging/", "Cargo.toml", "Cargo.lock", "research-lock.json"] +LAUNCHER_PATHS = ["launcher/", "crates/horizon-prepare/", "crates/horizon-theme/"] +LAUNCHER_IGNORED = ["launcher/links.json", "launcher/docs/", "launcher/tests/"] + +FOOTER = { + "game": "Install or update it from the Horizon launcher: it installs new versions by itself. " + "New here? Get the launcher at https://playhorizon.dev. You need your own copy of Minecraft: Java Edition.", + "launcher": "Your launcher updates itself. New here? Download the archive for your system below, extract it, " + "and run `horizon-launcher`. Website: https://playhorizon.dev", +} +DISCLAIMER = "Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft." + + +def run(*command, check=True): + result = subprocess.run(command, cwd=ROOT, capture_output=True, text=True) + if check and result.returncode: + raise SystemExit(f"{' '.join(command)}: {result.stderr.strip()}") + return result.stdout + + +def gh_json(*arguments): + return json.loads(run("gh", *arguments) or "null") + + +def exporters(): + """The exporter and oracle sources horizon-prepare compiles: those its sources name.""" + names = set() + for source in (ROOT / "crates" / "horizon-prepare" / "src").glob("*.rs"): + names.update(re.findall(r'"([A-Z]\w+\.java)"', source.read_text())) + return {EXPORTERS + name for name in names} + + +def player_facing(path, kind, exporter_paths=frozenset()): + """Whether a change to path ships to players in a release of this kind.""" + if path.endswith(".md") or re.match(r"(crates|launcher)/([\w-]+/)?(examples|tests|benches)/", path): + return False + if kind == "launcher": + return any(path.startswith(p) for p in LAUNCHER_PATHS) and not any(path.startswith(p) for p in LAUNCHER_IGNORED) + return any(path == p or path.startswith(p) for p in GAME_PATHS) or path in exporter_paths + + +def is_game_tag(tag): + return re.fullmatch(r"v\d{4}\.\d{2}\.\d{2}(\.\d+)?", tag) is not None + + +def is_launcher_tag(tag): + return re.fullmatch(r"launcher-v\d+\.\d+\.\d+", tag) is not None + + +def tag_key(tag): + return tuple(int(part) for part in re.findall(r"\d+", tag)) + + +def next_game_tag(tags, today): + """vYYYY.MM.DD, or .1, .2... when that day already has a tag (drafts and rolled-back releases included).""" + day = f"v{today:%Y.%m.%d}" + taken = [tag for tag in tags if tag == day or tag.startswith(day + ".")] + if not taken: + return day + return f"{day}.{max(int(tag.split('.')[3]) if tag.count('.') == 3 else 0 for tag in taken) + 1}" + + +def next_launcher_tag(tags, minor): + versions = sorted((tag_key(tag) for tag in tags if is_launcher_tag(tag)), reverse=True) + major, minor_, patch = versions[0] if versions else (0, 1, 0) + return f"launcher-v{major}.{minor_ + 1}.0" if minor else f"launcher-v{major}.{minor_}.{patch + 1}" + + +def merged_pull_requests(base, head): + """(number, merge commit) of the pull requests merged into main between base and head, oldest first.""" + found = [] + for line in run("git", "log", "--first-parent", "--reverse", "--format=%H%x09%s", f"{base}..{head}").splitlines(): + commit, _, subject = line.partition("\t") + match = re.match(r"Merge pull request #(\d+) ", subject) or re.search(r"\(#(\d+)\)$", subject) + if match: + found.append((int(match.group(1)), commit)) + return found + + +def changed_paths(commit): + """The files a pull request changed: its merge commit against main before it (first parent).""" + return run("git", "diff", "--name-only", f"{commit}^1", commit).split() + + +def pull_request(number): + data = gh_json("pr", "view", str(number), "--repo", REPO, "--json", + "number,title,url,labels,closingIssuesReferences,author") + return { + "number": data["number"], + "title": data["title"].strip(), + "url": data["url"], + "labels": sorted(label["name"] for label in data["labels"]), + "issues": sorted(issue["number"] for issue in data.get("closingIssuesReferences") or []), + "author": (data.get("author") or {}).get("login", ""), + } + + +def published_releases(): + """Published (not draft, not pre-release) releases, newest first, with their tags and dates.""" + releases = gh_json("api", f"repos/{REPO}/releases?per_page=100", "--paginate", "--slurp") + flat = [release for page in releases for release in page] + return [release for release in flat if not release["draft"] and not release["prerelease"]] + + +def last_release(releases, kind): + keep = is_game_tag if kind == "game" else is_launcher_tag + ours = [release for release in releases if keep(release["tag_name"])] + return max(ours, key=lambda release: tag_key(release["tag_name"]), default=None) + + +def decision(kind, prs, last_published, now, paused=False, force=False): + """Whether to release now, and why. prs: the merged pull requests since the last release, each with the + files it changed under "paths" (player-facing ones only).""" + counted = [pr for pr in prs if pr["paths"] and "skip-release" not in pr["labels"]] + urgent = [pr for pr in counted if "release-now" in pr["labels"]] + age = now - last_published if last_published else None + if force: + return True, "started by hand with force" + if paused: + return False, "RELEASES_PAUSED is set" + if not counted: + return False, "no merged pull request changed what players run" + if urgent: + return True, "release-now: " + ", ".join(f"#{pr['number']}" for pr in urgent) + if age is not None and age < COOLDOWN: + wait = COOLDOWN - age + return False, f"{len(counted)} pull requests wait for the cooldown ({wait.seconds // 60} more minutes)" + return True, f"{len(counted)} pull requests changed what players run" + + +def clause(title): + """The start of a pull request title, for a release's name: "Nether portals: vanilla timing" -> "Nether portals".""" + return re.split(r"[:;(]| — | - ", title, maxsplit=1)[0].strip().rstrip(".") + + +def summary(new, fixed, limit=72): + """A short name for the release, from its pull request titles, features first.""" + titles = [clause(pr["title"]) for pr in new[::-1] + fixed[::-1]] + shown, text = [], "" + for title in titles: + title = title if not shown or not title[1:2].islower() else title[0].lower() + title[1:] + candidate = ", ".join(shown + [title]) + if shown and len(candidate) > limit - 20: + break + shown.append(title) + text = candidate + rest = len(titles) - len(shown) + if rest: + text += f" and {rest} more {'changes' if new else 'fixes'}" + return text + + +def bullet(pr): + """A pull request as a line of notes: its title (written for people), its number and the issues it closes.""" + title = re.sub(r"\s*\((?:fixes|closes) #\d+\)|,? stacked on #\d+", "", pr["title"]).strip().rstrip(".") + issues = "".join(f", fixes #{issue}" for issue in pr["issues"]) + return f"- {title} (#{pr['number']}{issues})" + + +def known_issues(path=ROOT / "docs" / "known-issues.md"): + if not path.exists(): + return [] + return [line.rstrip() for line in path.read_text().splitlines() if line.startswith("- ")] + + +def notes(kind, version, prs, issues): + """(title, body) of a release.""" + shown = [pr for pr in prs if pr["paths"] and "skip-release" not in pr["labels"]] + new = [pr for pr in shown if "feature" in pr["labels"]] + fixed = [pr for pr in shown if "feature" not in pr["labels"]] + if kind == "game": + title = f"Horizon {version.removeprefix('v')}" + (f": {summary(new, fixed)}" if shown else "") + else: + title = f"Horizon launcher {version.removeprefix('launcher-v')}" + parts = [] if shown else ["Rebuilt from the latest main."] + if new: + parts.append("### New\n" + "\n".join(map(bullet, new))) + if fixed: + parts.append("### Fixed\n" + "\n".join(map(bullet, fixed))) + if issues and kind == "game": + parts.append("### Known issues\n" + "\n".join(issues)) + contributors = sorted({pr["author"] for pr in shown if pr["author"] and pr["author"] != REPO.split("/")[0]}) + if contributors: + parts.append("Thanks to " + ", ".join(f"@{name}" for name in contributors) + ".") + parts.append(FOOTER[kind]) + parts.append(DISCLAIMER) + return title, "\n\n".join(parts) + "\n" + + +def gather(kind, head, releases=None): + """The last published release of this kind and the pull requests merged since, with their player-facing paths.""" + releases = published_releases() if releases is None else releases + last = last_release(releases, kind) + base = last["tag_name"] if last else run("git", "rev-list", "--max-parents=0", head).split()[0] + exporter_paths = exporters() + prs = [] + for number, commit in merged_pull_requests(base, head): + pr = pull_request(number) + pr["paths"] = [path for path in changed_paths(commit) if player_facing(path, kind, exporter_paths)] + prs.append(pr) + return last, prs + + +def green_main_head(): + """The newest commit on main whose checks passed: what an automatic release builds.""" + runs = gh_json("run", "list", "--repo", REPO, "--workflow", "checks", "--branch", "main", "--event", "push", + "--limit", "10", "--json", "headSha,status,conclusion") + for entry in runs: + if entry["status"] == "completed": + return entry["headSha"] if entry["conclusion"] == "success" else None + return None + + +def write_outputs(values): + if os.environ.get("GITHUB_OUTPUT"): + with open(os.environ["GITHUB_OUTPUT"], "a") as out: + for name, value in values.items(): + out.write(f"{name}={value}\n") + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("command", choices=["decide", "notes"]) + parser.add_argument("--kind", choices=["game", "launcher"], required=True) + parser.add_argument("--head", help="the commit to release (default: the newest commit on main whose checks passed)") + parser.add_argument("--tag", help="notes: the release's tag") + parser.add_argument("--force", action="store_true", help="release even without player-facing changes or within the cooldown") + parser.add_argument("--out", type=Path, help="notes: write title.txt and body.md here") + parser.add_argument("--now", help="the time to decide at (ISO 8601; default now)") + args = parser.parse_args() + now = dt.datetime.fromisoformat(args.now) if args.now else dt.datetime.now(dt.timezone.utc) + + head = args.head or green_main_head() + if not head: + result = {"release": False, "reason": "main's latest checks did not pass"} + print(json.dumps(result, indent=1)) + write_outputs({"release": "false", "reason": result["reason"]}) + return 0 + head = run("git", "rev-parse", head).strip() + last, prs = gather(args.kind, head) + if args.command == "notes": + version = args.tag or "unreleased" + title, body = notes(args.kind, version, prs, known_issues()) + if args.out: + args.out.mkdir(parents=True, exist_ok=True) + (args.out / "title.txt").write_text(title + "\n") + (args.out / "body.md").write_text(body) + print(title + "\n\n" + body) + return 0 + + published = dt.datetime.fromisoformat(last["published_at"].replace("Z", "+00:00")) if last else None + release, reason = decision(args.kind, prs, published, now, os.environ.get("RELEASES_PAUSED") == "1", args.force) + tags = run("git", "tag", "--list").split() + minor = any("feature" in pr["labels"] for pr in prs if pr["paths"]) + tag = next_game_tag(tags, now.date()) if args.kind == "game" else next_launcher_tag(tags, minor) + result = { + "release": release, "reason": reason, "tag": tag, "head": head, + "last": last["tag_name"] if last else None, "last_published": last["published_at"] if last else None, + "pull_requests": [{key: pr[key] for key in ("number", "title", "labels", "paths")} for pr in prs], + } + print(json.dumps(result, indent=1)) + write_outputs({"release": str(release).lower(), "reason": reason, "tag": tag, "head": head}) + return 0 + + +if __name__ == "__main__": + sys.exit(main())