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 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-14 18:48:29 +02:00
parent 9e016b6235
commit 8aacb48798
6 changed files with 748 additions and 40 deletions
+203 -40
View File
@@ -1,57 +1,220 @@
name: release builds
# Started by hand: gh workflow run release.yml --ref <branch>
# 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 <branch> # 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/
+6
View File
@@ -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.
+115
View File
@@ -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<br/>parity"}
checks -- green --> automerge["auto-merge<br/>(merge commit)"]
automerge --> main(["main"])
main --> mainchecks{"checks on main"}
mainchecks -- green --> decide{"decide<br/>tools/release_train.py"}
cron(["every hour :17"]) --> decide
decide -- "player-facing PRs, 3 h since the last release,<br/>or release-now" --> build
decide -- otherwise --> wait(["wait"])
subgraph build["build, in parallel"]
linux["Linux x86_64<br/>GitHub ubuntu-22.04"]
windows["Windows x64<br/>GitHub windows-latest"]
mac["macOS arm64<br/>Mac mini runner<br/>+ offscreen game run"]
end
build --> publish["publish vYYYY.MM.DD[.N]<br/>notes from the merged PRs"]
publish --> launcher(["launchers install it"])
publish --> kira(["Kira posts it;<br/>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: <the first pull request titles>`, 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 <branch> # 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.
+23
View File
@@ -1537,6 +1537,29 @@ mod tests {
assert_eq!(launcher, ["launcher-v9.0.0"]);
}
/// Rolling a release back (`gh release edit <tag> --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<String> = 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);
+99
View File
@@ -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()
+302
View File
@@ -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())