diff --git a/.github/workflows/promote.yml b/.github/workflows/promote.yml new file mode 100644 index 000000000..b7ef0b38b --- /dev/null +++ b/.github/workflows/promote.yml @@ -0,0 +1,52 @@ +name: promote +# Beta game releases become stable (docs/release-flow.md, "Channels"): every 30 minutes tools/release_channels.py +# promotes the newest beta that has been out 6 hours, passed its release smoke test and isn't covered by an issue +# labelled release-blocker. By hand, from GitHub's app too (Actions > promote > Run workflow): +# gh workflow run promote -f tag=v2026.10.19.03 # that beta now, without the wait +# gh workflow run promote -f tag=v2026.10.19.03 -f force=true # even blocked or without its smoke test +# gh workflow run promote -f dry_run=true # say what would be promoted +# Holding betas back: label an issue release-blocker. While it is open it holds every beta; closed as completed it +# still holds the betas published before it closed. The issue's text is never read (its author could edit it). +# When the oldest waiting beta is 24 hours old, an issue "Promotion to stable has stalled" says so; it closes itself +# after the next promotion. +on: + schedule: + - cron: '13,43 * * * *' + workflow_dispatch: + inputs: + tag: + description: The beta to promote now (empty = the newest beta that is due) + type: string + default: '' + force: + description: Promote that tag even if a release-blocker covers it or its smoke test didn't run + type: boolean + default: false + dry_run: + description: Say what would be promoted, change nothing + type: boolean + default: false +permissions: + contents: write + issues: write +concurrency: + group: promote + cancel-in-progress: false +jobs: + promote: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + with: + # The notes of a promoted release cover every pull request since the last stable one. + fetch-depth: 0 + # gh uses GH_TOKEN below; nothing needs git credentials on disk. + persist-credentials: false + - name: Promote + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ inputs.tag }} + FORCE: ${{ inputs.force && 'yes' || '' }} + DRY_RUN: ${{ (inputs.dry_run || github.ref != 'refs/heads/main') && 'yes' || '' }} + run: python3 tools/release_channels.py promote ${TAG:+--tag "$TAG"} ${FORCE:+--force} ${DRY_RUN:+--dry-run} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a8f5f9bb5..546c6707e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,7 +6,8 @@ name: release # 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. +# publishes vYYYY.MM.DD[.N] with notes from the merged pull requests, as a beta (a pre-release) that promote.yml makes +# stable after 6 hours. # 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: @@ -171,6 +172,15 @@ jobs: or not report.get("meshed_sections") or not report.get("player"): sys.exit("the smoke run did not draw a world") EOF + # Published with the release: a beta becomes stable only with it (tools/release_channels.py). + cp "$home/smoke.json" "$RUNNER_TEMP/smoke-test.json" + - uses: actions/upload-artifact@v4 + if: runner.environment == 'self-hosted' + with: + name: smoke-test.json + path: ${{ runner.temp }}/smoke-test.json + if-no-files-found: error + retention-days: 3 - name: Package run: | set -euo pipefail @@ -296,9 +306,12 @@ jobs: TAG: ${{ needs.decide.outputs.tag }} run: | signature=(); [[ -f dist/SHA256SUMS.sig ]] && signature=(dist/SHA256SUMS.sig) + smoke=(); [[ -f dist/smoke-test.json ]] && smoke=(dist/smoke-test.json) + # A beta (pre-release): promote.yml makes it stable and latest after 6 hours (docs/release-flow.md). 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 dist/horizon-server-linux-x86_64.tar.gz dist/SHA256SUMS "${signature[@]}" + --notes-file notes/body.md --prerelease --latest=false dist/horizon-linux-x86_64.tar.gz \ + dist/horizon-windows-x64.zip dist/horizon-macos-arm64.zip dist/horizon-server-linux-x86_64.tar.gz \ + dist/SHA256SUMS "${signature[@]}" "${smoke[@]}" - name: Dry run, the release that would be published if: needs.decide.outputs.dry_run == 'true' run: | diff --git a/docs/release-flow.md b/docs/release-flow.md index 3386b4af2..354f9aff2 100644 --- a/docs/release-flow.md +++ b/docs/release-flow.md @@ -1,8 +1,9 @@ # Release flow How a change gets from a pull request to players: the checks a pull request passes, how it merges, and the -automatic releases that follow. Releases are automatic and frequent so the latest Horizon is always playable; -there is no separate development channel. +automatic releases that follow. Releases are automatic and frequent so the latest Horizon is always playable. +Each one goes out as a **beta** and becomes **stable** 6 hours later unless something holds it back +([Channels](#channels)): launchers and servers install stable builds unless their owner turns betas on. ## Pull request checks @@ -99,9 +100,12 @@ flowchart LR 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"]) + build --> publish["publish vYYYY.MM.DD[.N] as a beta
notes from the merged PRs"] + publish --> beta(["launchers with Beta builds on install it"]) + publish --> promote{"promote.yml, every 30 min:
6 h old, smoke test, no release-blocker"} + promote --> stable["stable and latest
notes since the last stable"] + stable --> launcher(["every launcher and server installs it"]) + stable --> kira(["Kira posts it;
pings only with ### New"]) ``` ### When it releases @@ -131,6 +135,7 @@ commits) since the last **published** game release: | `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 | +| `release-blocker` | On an issue: holds every beta back from stable while it is open ([Channels](#channels)) | Pull requests without `feature` are listed under **Fixed**. Titles are written for players, since they become the notes. @@ -162,6 +167,47 @@ runs the game: GitHub's runners have neither a GPU worth the name nor the game f Kira posts every published release in #releases and pings the releases role only when the notes have a `### New` section. +### Channels + +Every game release is published as a **beta**, a GitHub pre-release, so GitHub's *latest* release stays the last +**stable** one. Launchers and `horizon-server update` install stable builds by default (the launcher's Settings +has a "Beta builds" switch; `horizon-server update --version ` takes one by name), and Kira announces a release +when it becomes stable: Discord's #releases only ever shows stable ones. + +`.github/workflows/promote.yml` runs `tools/release_channels.py promote` every 30 minutes. It promotes the newest +beta that + +- is newer than the stable release, +- has been out 6 hours, +- passed its release smoke test: the macOS build attaches `smoke-test.json` (the offscreen game run's report) only + when the game drew a world on the Mac mini, so a release built while `MAC_RUNNER` sends macOS to GitHub waits + for a hand, +- and isn't covered by an issue labelled `release-blocker`. An open blocker holds every beta; closed as completed + it still holds the betas published before it closed (they have the bug); closed as not planned it holds + nothing. Only the label and the issue's state count, never its text: whoever opened the issue can edit the + text after a maintainer labels it, so it can't pick which betas go out. + +Nothing older than the stable release is ever promoted, not even with `force`: GitHub's latest release is what +`horizon-server update` and `install.sh` download, so it only moves forward. + +When the oldest beta newer than the stable release has waited 24 hours, promote.yml opens an issue titled +"Promotion to stable has stalled" with the reason from the last check (a blocker left open, smoke tests not +running). It closes itself after the next promotion. + +Promoting marks the beta stable and latest and rewrites its notes to list everything since the previous stable +release (`release_train.py notes --stable`), so players who skipped the betas see all of it. Older betas stay +betas. By hand, from a phone too (GitHub app: Actions, promote, Run workflow): + +```sh +gh workflow run promote -f tag=v2026.10.19.03 # that beta now: no 6-hour wait, still no blocker +gh workflow run promote -f tag=v2026.10.19.03 -f force=true # even blocked or without a smoke test +gh workflow run promote -f dry_run=true # what would be promoted now +``` + +A beta's notes cover only what changed since the release before it (beta or stable), and say it is a beta. +`release_train.py decide` counts pull requests from the newest release of either channel, so betas don't +release the same changes again. + ### Signed checksums Every game and launcher release carries `SHA256SUMS` (the archives' SHA-256, `sha256sum`'s format) and @@ -225,7 +271,8 @@ A bad release is withdrawn by turning it back into a draft: gh release edit v2026.10.15.01 --draft ``` -Launchers list only published releases: the previous version becomes the newest one again, launchers that +A beta that is not promoted yet needs no rollback: label an issue about it `release-blocker`. For a stable +release: launchers list only published releases, so 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 diff --git a/tests/test_release_channels.py b/tests/test_release_channels.py new file mode 100644 index 000000000..0b27ae8a3 --- /dev/null +++ b/tests/test_release_channels.py @@ -0,0 +1,107 @@ +import datetime as dt +import unittest + +from tools import release_channels as channels +from tools import release_train as train + +NOW = dt.datetime(2026, 10, 19, 18, 0, tzinfo=dt.timezone.utc) + + +def release(tag, hours_ago, prerelease=True, smoke=True, draft=False): + published = (NOW - dt.timedelta(hours=hours_ago)).isoformat().replace("+00:00", "Z") + assets = [{"name": "horizon-linux-x86_64.tar.gz"}] + ([{"name": channels.SMOKE_ASSET}] if smoke else []) + return {"tag_name": tag, "published_at": published, "prerelease": prerelease, "draft": draft, "assets": assets} + + +def blocker(number, title, body="", state="open", reason=None, closed_hours_ago=None): + closed = None if closed_hours_ago is None else (NOW - dt.timedelta(hours=closed_hours_ago)).isoformat() + return {"number": number, "title": title, "body": body, "state": state, "state_reason": reason, "closed_at": closed} + + +STABLE = release("v2026.10.18.04", 30, prerelease=False) + + +class ReleaseChannelTests(unittest.TestCase): + def test_the_newest_beta_out_six_hours_with_a_smoke_test_is_promoted(self): + releases = [STABLE, release("v2026.10.19", 9), release("v2026.10.19.01", 7), release("v2026.10.19.02", 2)] + chosen, why = channels.choose(releases, [], NOW) + self.assertEqual(chosen["tag_name"], "v2026.10.19.01") + self.assertIn("6 h", why) + + def test_nothing_is_due_before_six_hours(self): + chosen, why = channels.choose([STABLE, release("v2026.10.19", 5.5)], [], NOW) + self.assertIsNone(chosen) + self.assertIn("0 h 30 min to go", why) + + def test_a_beta_without_its_smoke_test_waits_for_a_hand(self): + releases = [STABLE, release("v2026.10.19", 8, smoke=False)] + self.assertIsNone(channels.choose(releases, [], NOW)[0]) + self.assertIsNone(channels.choose(releases, [], NOW, tag="v2026.10.19")[0]) + self.assertEqual(channels.choose(releases, [], NOW, tag="v2026.10.19", force=True)[0]["tag_name"], "v2026.10.19") + + def test_by_hand_skips_the_wait_but_not_a_blocker(self): + releases = [STABLE, release("v2026.10.19.02", 1)] + self.assertEqual(channels.choose(releases, [], NOW, tag="v2026.10.19.02")[0]["tag_name"], "v2026.10.19.02") + blocked = [blocker(5, "Crash on start in 2026.10.19.2")] + chosen, why = channels.choose(releases, blocked, NOW, tag="v2026.10.19.02") + self.assertIsNone(chosen) + self.assertIn("#5", why) + self.assertIsNotNone(channels.choose(releases, blocked, NOW, tag="v2026.10.19.02", force=True)[0]) + + def test_stable_releases_and_drafts_are_never_promoted(self): + self.assertIsNone(channels.choose([STABLE], [], NOW, tag=STABLE["tag_name"])[0]) + withdrawn = release("v2026.10.19", 9, draft=True) + self.assertIsNone(channels.choose([STABLE, withdrawn], [], NOW)[0]) + older = release("v2026.10.18.03", 40) + self.assertIsNone(channels.choose([STABLE, older], [], NOW)[0]) + + def test_an_open_blocker_holds_every_beta_whatever_its_text_says(self): + releases = [STABLE, release("v2026.10.19", 12), release("v2026.10.19.01", 10), release("v2026.10.19.02", 8)] + # The issue's author can edit its text after it is labelled: naming a later version must not free a beta. + for text in ("Something is badly wrong", "Only in v2099.01.01", "Since v2026.10.19.01 the chests…"): + chosen, why = channels.choose(releases, [blocker(7, text, body=text)], NOW) + self.assertIsNone(chosen, text) + self.assertIn("release-blocker #7", why) + + def test_a_fixed_blocker_still_holds_the_betas_published_before_the_fix(self): + fixed = blocker(9, "Crash", state="closed", reason="completed", closed_hours_ago=7.5) + releases = [STABLE, release("v2026.10.19", 12), release("v2026.10.19.01", 7)] + self.assertEqual(channels.choose(releases, [fixed], NOW)[0]["tag_name"], "v2026.10.19.01") + self.assertIsNone(channels.choose(releases[:2], [fixed], NOW)[0]) + not_planned = blocker(10, "Crash", state="closed", reason="not_planned", closed_hours_ago=1) + self.assertEqual(channels.choose(releases[:2], [not_planned], NOW)[0]["tag_name"], "v2026.10.19") + + def test_force_never_moves_latest_backwards(self): + # horizon-server update and install.sh download GitHub's latest: an older beta must never become it. + older = release("v2026.10.18.03", 40, smoke=False) + chosen, why = channels.choose([STABLE, older], [blocker(3, "x")], NOW, tag="v2026.10.18.03", force=True) + self.assertIsNone(chosen) + self.assertIn("not newer than the stable v2026.10.18.04", why) + same = release("v2026.10.18.04", 30, prerelease=False) + self.assertIsNone(channels.choose([same], [], NOW, tag="v2026.10.18.04", force=True)[0]) + + def test_a_stall_is_reported_once_the_oldest_waiting_beta_is_a_day_old(self): + self.assertIsNone(channels.stalled([STABLE, release("v2026.10.19", 23), release("v2026.10.19.01", 2)], NOW)) + releases = [STABLE, release("v2026.10.19", 25), release("v2026.10.19.01", 2)] + oldest, age = channels.stalled(releases, NOW) + self.assertEqual(oldest["tag_name"], "v2026.10.19") + title, body = channels.stall_issue(releases, (oldest, age), "no beta is due (release-blocker #4)") + self.assertEqual(title, "Promotion to stable has stalled: v2026.10.19 has waited 25 h") + self.assertIn("v2026.10.18.04", body) + self.assertIn("release-blocker #4", body) + # Betas older than the stable release are contained in it: they aren't waiting. + self.assertIsNone(channels.stalled([STABLE, release("v2026.10.18.03", 40)], NOW)) + self.assertIsNone(channels.stalled([STABLE], NOW)) + + def test_beta_notes_say_so_and_stable_notes_do_not(self): + pr = {"number": 1, "title": "Fix a thing", "labels": [], "paths": ["crates/x.rs"], "issues": [], "author": "ludovic111"} + _, beta = train.notes("game", "v2026.10.19", [pr], [], beta=True) + _, stable = train.notes("game", "v2026.10.19", [pr], [], beta=False) + self.assertIn("beta build", beta) + self.assertNotIn("beta build", stable) + _, launcher = train.notes("launcher", "launcher-v0.9.0", [pr], [], beta=True) + self.assertNotIn("beta build", launcher) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/release_channels.py b/tools/release_channels.py new file mode 100644 index 000000000..3ae58a84b --- /dev/null +++ b/tools/release_channels.py @@ -0,0 +1,211 @@ +#!/usr/bin/env python3 +"""Promotes Horizon's beta game releases to stable (.github/workflows/promote.yml, docs/release-flow.md). + + python3 tools/release_channels.py promote # the newest beta that is due, if any + python3 tools/release_channels.py promote --tag v2026.10.19.03 # that beta now (by hand) + python3 tools/release_channels.py promote --tag v2026.10.19.03 --force # even if blocked or untested + python3 tools/release_channels.py promote --dry-run # say what would happen, change nothing + +Every game release goes out as a beta (a GitHub pre-release). A beta is due for stable when: +- it is newer than the stable release (GitHub's "latest", which launchers and servers install by default), +- it has been out PROMOTE_AFTER (6 hours) without trouble; a promotion by hand (--tag) skips the wait, +- its release smoke test passed: release.yml attaches smoke-test.json only after the Mac mini ran the game, +- and no issue labelled release-blocker covers it. An open blocker holds every beta; one closed as completed keeps + holding the betas published before it closed (they still have the bug); one closed as not planned holds nothing. + Only people who can triage the repository can add the label, and the issue's text is never read: whoever wrote + the issue could edit it afterwards, so it can't decide which betas go out. + +The newest due beta is promoted: marked stable and latest, with notes covering everything since the previous +stable release (tools/release_train.py notes --stable). Older betas stay betas: the stable one contains them. +Nothing older than the current stable release is ever promoted, even with --force: GitHub's "latest" is what +horizon-server update and install.sh download, and it only moves forward. + +When the oldest beta newer than the stable release has waited STALL_AFTER (24 hours), promotion has stalled +(blocked, smoke tests not running, the schedule off): an issue says so, and is closed once a beta is promoted. +""" + +import argparse +import datetime as dt +import json +import os +from pathlib import Path +import re +import subprocess +import sys +import tempfile + +ROOT = Path(__file__).resolve().parents[1] +REPO = os.environ.get("GITHUB_REPOSITORY", "ludovic111/horizon") +PROMOTE_AFTER = dt.timedelta(hours=6) +SMOKE_ASSET = "smoke-test.json" +BLOCKER = "release-blocker" +STALL_AFTER = dt.timedelta(hours=24) +STALLED = "Promotion to stable has stalled" +GAME_TAG = re.compile(r"v\d{4}\.\d{2}\.\d{2}(?:\.\d+)?") + + +def tag_key(tag): + """A game tag's numbers, four of them (v2026.10.19 is (2026, 10, 19, 0)), so tags compare.""" + version = tuple(int(part) for part in re.findall(r"\d+", tag)) + return version + (0,) * (4 - len(version)) + + +def parse_time(text): + return dt.datetime.fromisoformat(text.replace("Z", "+00:00")) if text else None + + +def covers(blocker, release): + """Whether a release-blocker issue holds this beta back. Only its state and dates count, never its text.""" + if blocker.get("state") != "closed": + return True + closed = parse_time(blocker.get("closed_at")) + return blocker.get("state_reason") == "completed" and bool(closed) and parse_time(release["published_at"]) < closed + + +def stable(releases): + """The newest stable (non pre-release) game release.""" + stables = [r for r in releases if not r["prerelease"]] + return max(stables, key=lambda r: tag_key(r["tag_name"]), default=None) + + +def reasons_against(release, current, blockers, now, by_hand=False): + """Why this beta can't become stable now: an empty list when it can.""" + reasons = [] + if not release["prerelease"]: + reasons.append("it is already stable") + if current and tag_key(release["tag_name"]) <= tag_key(current["tag_name"]): + reasons.append(f"it is not newer than the stable {current['tag_name']}") + age = now - parse_time(release["published_at"]) + if not by_hand and age < PROMOTE_AFTER: + left = PROMOTE_AFTER - age + reasons.append(f"it has been out {age.seconds // 3600} h {age.seconds % 3600 // 60} min, " + f"{left.seconds // 3600} h {left.seconds % 3600 // 60} min to go") + if not any(asset["name"] == SMOKE_ASSET for asset in release.get("assets", [])): + reasons.append(f"it has no {SMOKE_ASSET}: the release smoke test did not run") + for blocker in blockers: + if covers(blocker, release): + reasons.append(f"release-blocker #{blocker['number']}") + return reasons + + +def choose(releases, blockers, now, tag=None, force=False): + """(the beta to promote or None, a line saying why) for the game releases `releases`.""" + games = [r for r in releases if not r["draft"] and GAME_TAG.fullmatch(r["tag_name"])] + current = stable(games) + if tag: + release = next((r for r in games if r["tag_name"] == tag), None) + if not release: + return None, f"no published game release is tagged {tag}" + reasons = reasons_against(release, current, blockers, now, by_hand=True) + if force: + # Even forced, "latest" only moves forward: horizon-server update and install.sh follow it. + reasons = [r for r in reasons if r == "it is already stable" or r.startswith("it is not newer")] + if reasons: + return None, f"{tag} stays a beta: " + "; ".join(reasons) + return release, f"{tag} promoted by hand" + (" with force" if force else "") + betas = sorted((r for r in games if r["prerelease"]), key=lambda r: tag_key(r["tag_name"]), reverse=True) + held = [] + for release in betas: + reasons = reasons_against(release, current, blockers, now) + if not reasons: + return release, f"{release['tag_name']} has been out {PROMOTE_AFTER.seconds // 3600} h, passed its smoke test " \ + "and no release-blocker covers it" + held.append(f"{release['tag_name']}: " + "; ".join(reasons)) + return None, "no beta is due" + (" (" + " / ".join(held[:3]) + ")" if held else "") + + +def stalled(releases, now): + """(the oldest beta newer than the stable release, how long it has waited) once that is STALL_AFTER, else None.""" + games = [r for r in releases if not r["draft"] and GAME_TAG.fullmatch(r["tag_name"])] + current = stable(games) + waiting = [r for r in games if r["prerelease"] and (not current or tag_key(r["tag_name"]) > tag_key(current["tag_name"]))] + if not waiting: + return None + oldest = min(waiting, key=lambda r: parse_time(r["published_at"])) + age = now - parse_time(oldest["published_at"]) + return (oldest, age) if age >= STALL_AFTER else None + + +def stall_issue(releases, stall, reason): + """The title and body of the issue saying promotion has stalled.""" + oldest, age = stall + current = stable([r for r in releases if not r["draft"] and GAME_TAG.fullmatch(r["tag_name"])]) + hours = int(age.total_seconds() // 3600) + body = (f"Opened by .github/workflows/promote.yml, not by a person.\n\n" + f"No beta has become stable for {hours} hours: {oldest['tag_name']} has waited since " + f"{oldest['published_at']}, and launchers, servers and install.sh still get " + f"{current['tag_name'] if current else 'no stable release'}.\n\n" + f"The last check said: {reason}\n\n" + "Usual causes: an open `release-blocker` issue (it holds every beta until it is closed), the Mac mini's " + "release smoke test not running (no smoke-test.json on the betas), or the promote workflow disabled. " + "To promote a beta by hand: `gh workflow run promote -f tag=` (add `-f force=true` to skip the " + "smoke test and blockers). This issue closes itself once a beta is promoted.") + return f"{STALLED}: {oldest['tag_name']} has waited {hours} h", body + + +def gh(*arguments, capture=True): + result = subprocess.run(["gh", *arguments], cwd=ROOT, capture_output=capture, text=True) + if result.returncode: + raise SystemExit(f"gh {' '.join(arguments)}: {(result.stderr or '').strip()}") + return result.stdout + + +def gh_pages(path): + return [item for page in json.loads(gh("api", path, "--paginate", "--slurp") or "[]") for item in page] + + +def promote(release): + """Marks the beta stable and latest, with notes covering everything since the previous stable release.""" + tag = release["tag_name"] + with tempfile.TemporaryDirectory() as out: + subprocess.run([sys.executable, str(ROOT / "tools" / "release_train.py"), "notes", "--kind", "game", "--tag", tag, + "--head", tag, "--stable", "--out", out], cwd=ROOT, check=True, stdout=subprocess.DEVNULL) + title = (Path(out) / "title.txt").read_text().strip() + gh("release", "edit", tag, "--repo", REPO, "--prerelease=false", "--latest", "--title", title, + "--notes-file", str(Path(out) / "body.md")) + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("command", choices=["promote"]) + parser.add_argument("--tag", help="promote this beta now (by hand: no 6-hour wait)") + parser.add_argument("--force", action="store_true", help="with --tag: even without a smoke test or with a blocker") + parser.add_argument("--dry-run", action="store_true", help="say what would be promoted, change nothing") + parser.add_argument("--now", help="the time to decide at (ISO 8601; default now)") + args = parser.parse_args() + if args.force and not args.tag: + parser.error("--force needs --tag: only a named beta is forced") + now = dt.datetime.fromisoformat(args.now) if args.now else dt.datetime.now(dt.timezone.utc) + releases = gh_pages(f"repos/{REPO}/releases?per_page=100") + blockers = [issue for issue in gh_pages(f"repos/{REPO}/issues?labels={BLOCKER}&state=all&per_page=100") + if "pull_request" not in issue] + release, reason = choose(releases, blockers, now, args.tag, args.force) + if release and not args.dry_run: + promote(release) + line = ("Would promote: " if release and args.dry_run else "") + reason + print(line) + if os.environ.get("GITHUB_STEP_SUMMARY"): + with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary: + summary.write(f"### {line}\n") + report_stall(releases, release, reason, now, args.dry_run) + return 1 if args.tag and not release else 0 + + +def report_stall(releases, promoted, reason, now, dry_run): + """Opens the stalled-promotion issue when one is due and none is open; closes it after a promotion.""" + open_issues = [issue for issue in gh_pages(f"repos/{REPO}/issues?state=open&per_page=100") + if "pull_request" not in issue and issue["title"].startswith(STALLED)] + stall = None if promoted else stalled(releases, now) + if stall and not open_issues: + title, body = stall_issue(releases, stall, reason) + print(("Would open: " if dry_run else "Opening: ") + title) + if not dry_run: + gh("issue", "create", "--repo", REPO, "--title", title, "--body", body) + if promoted and not dry_run: + for issue in open_issues: + gh("issue", "close", str(issue["number"]), "--repo", REPO, "--comment", + f"{promoted['tag_name']} is stable now (promote.yml).") + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/release_train.py b/tools/release_train.py index 70e7b0287..943c650d2 100644 --- a/tools/release_train.py +++ b/tools/release_train.py @@ -4,6 +4,7 @@ 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 + python3 tools/release_train.py notes --kind game --tag v2026.10.15 --head v2026.10.15 --stable # at promotion 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 the newest of them merged at least DEBOUNCE ago (a burst @@ -14,7 +15,9 @@ towards a release and aren't listed in the notes. RELEASES_PAUSED=1 (a repositor Game releases are tagged vYYYY.MM.DD, then .01, .02 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. +docs/known-issues.md. Game releases go out as betas (GitHub pre-releases) and tools/release_channels.py promotes +them to stable; a beta's notes cover what changed since the release before it (beta or stable), a promoted +release's (--stable) everything since the last stable one. 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. """ @@ -55,6 +58,8 @@ 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.", + "beta": "This is a beta build: launchers with Beta builds turned on in Settings install it now; everyone gets it " + "once it has been out 6 hours without a release-blocker.", "launcher": "Your launcher updates itself. New here? Download the archive for your system below, extract it, " "and run `horizon-launcher`. Website: https://playhorizon.dev", } @@ -149,11 +154,11 @@ def pull_request(number): } -def published_releases(): - """Published (not draft, not pre-release) releases, newest first, with their tags and dates.""" +def published_releases(betas=True): + """Published (not draft) releases with their tags and dates; without betas (pre-releases) when betas is False.""" 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"]] + return [release for release in flat if not release["draft"] and (betas or not release["prerelease"])] def last_release(releases, kind): @@ -225,8 +230,8 @@ def known_issues(path=ROOT / "docs" / "known-issues.md"): return [line.rstrip() for line in path.read_text().splitlines() if line.startswith("- ")] -def notes(kind, version, prs, issues): - """(title, body) of a release.""" +def notes(kind, version, prs, issues, beta=False): + """(title, body) of a release; a game beta's say it is one.""" 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"]] @@ -244,14 +249,17 @@ def notes(kind, version, prs, 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) + ".") + if beta and kind == "game": + parts.append(FOOTER["beta"]) 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 +def gather(kind, head, releases=None, betas=True): + """The last published release of this kind (stable only when betas is False) and the pull requests merged + since, with their player-facing paths.""" + releases = published_releases(betas) 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() @@ -289,6 +297,8 @@ def main(): parser.add_argument("--force", action="store_true", help="release even without player-facing changes, before merges settle or while paused") 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)") + parser.add_argument("--stable", action="store_true", + help="notes: for promoting a beta to stable, so since the last stable release, without the beta line") args = parser.parse_args() now = dt.datetime.fromisoformat(args.now) if args.now else dt.datetime.now(dt.timezone.utc) @@ -299,10 +309,10 @@ def main(): write_outputs({"release": "false", "reason": result["reason"]}) return 0 head = run("git", "rev-parse", head).strip() - last, prs = gather(args.kind, head) + last, prs = gather(args.kind, head, betas=not args.stable) if args.command == "notes": version = args.tag or "unreleased" - title, body = notes(args.kind, version, prs, known_issues()) + title, body = notes(args.kind, version, prs, known_issues(), beta=not args.stable) if args.out: args.out.mkdir(parents=True, exist_ok=True) (args.out / "title.txt").write_text(title + "\n") diff --git a/website/build.mjs b/website/build.mjs index 442ad9996..28c9c99fd 100644 --- a/website/build.mjs +++ b/website/build.mjs @@ -38,15 +38,18 @@ try { console.warn(`links.json: ${e.message}; using the built-in links`); } +// An optional token (a Railway variable, or `gh auth token` locally) lifts the rate limit. +const githubHeaders = { Accept: "application/vnd.github+json", ...(process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}) }; let releases = []; try { - const res = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=100`, { - // An optional token (a Railway variable, or `gh auth token` locally) lifts the rate limit. - headers: { Accept: "application/vnd.github+json", ...(process.env.GITHUB_TOKEN ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}) }, - signal: AbortSignal.timeout(15000), - }); + const res = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=100`, { headers: githubHeaders, signal: AbortSignal.timeout(15000) }); if (res.ok) releases = (await res.json()).filter((r) => !r.draft); else console.warn(`releases: ${res.status} from GitHub; the page will load them itself`); + // A day of betas can push the stable release out of the newest 100: it is GitHub's "latest" (betas never are). + if (res.ok && !releases.some((r) => /^v\d{4}\./.test(r.tag_name) && !r.prerelease)) { + const latest = await fetch(`https://api.github.com/repos/${REPO}/releases/latest`, { headers: githubHeaders, signal: AbortSignal.timeout(15000) }); + if (latest.ok) releases.push(await latest.json()); + } } catch (e) { console.warn(`releases: ${e.message}; the page will load them itself`); } diff --git a/website/src/main.js b/website/src/main.js index e4523fd25..825de1f25 100644 --- a/website/src/main.js +++ b/website/src/main.js @@ -39,14 +39,21 @@ const slim = (r) => ({ body: r.body || "", assets: r.assets.map((a) => ({ name: a.name, browser_download_url: a.browser_download_url, size: a.size })), }); +const isGame = (tag) => /^v\d{4}\.\d{1,2}\.\d{1,2}/.test(tag); const isLauncher = (r) => r.tag_name.startsWith("launcher-v") && !r.prerelease; const versionKey = (tag) => tag.replace("launcher-v", "").split(".").map(Number); const newer = (a, b) => versionKey(b).reduce((d, n, i) => d || n - (versionKey(a)[i] || 0), 0); -// The newest 30 releases. Game releases come out several times a day, so the newest launcher release can be -// older than all of them: then it is looked up by its tag (the newest launcher-v tag with a published release). +// The newest 100 releases (GitHub's most per page). Game betas come out several times a day, so the stable game +// release and the newest launcher release can both be older than all of them. The stable game release is then +// GitHub's "latest" (betas and launcher releases are never marked latest); the launcher release is looked up by its +// tag (the newest launcher-v tag with a published release). async function loadReleases() { - const list = (await get(`https://api.github.com/repos/${REPO}/releases?per_page=30`)).filter((r) => !r.draft).map(slim); + const list = (await get(`https://api.github.com/repos/${REPO}/releases?per_page=100`)).filter((r) => !r.draft).map(slim); + if (!list.some((r) => isGame(r.tag_name) && !r.prerelease)) { + const latest = await get(`https://api.github.com/repos/${REPO}/releases/latest`).catch(() => null); + if (latest && !latest.draft) list.push(slim(latest)); + } if (list.some(isLauncher)) return list; const refs = await get(`https://api.github.com/repos/${REPO}/git/matching-refs/tags/launcher-v`).catch(() => []); const tags = refs.map((r) => r.ref.replace("refs/tags/", "")).filter((t) => /^launcher-v\d+\.\d+\.\d+$/.test(t)).sort(newer); @@ -99,8 +106,6 @@ async function setUpDownload() { // --- Patch notes and the links from main --------------------------------- -const isGame = (tag) => /^v\d{4}\.\d{1,2}\.\d{1,2}/.test(tag); - async function setUpNotes() { const list = (await releases).filter((r) => isGame(r.tag_name) && !r.prerelease); if (list.length) document.getElementById("releases").innerHTML = releasesHtml(list.slice(0, 3));