Merge pull request #229 from ludovic111/ci/release-debounce

Release train: ship every settled player-facing change, no 3-hour gap
This commit is contained in:
Ludovic Marie
2026-10-15 01:01:37 +02:00
committed by GitHub
5 changed files with 59 additions and 42 deletions
+4 -3
View File
@@ -1,7 +1,8 @@
name: launcher
# Builds the launcher on Linux, macOS and Windows, and releases it by itself (docs/release-flow.md): after a
# push to main that changes the launcher or what it builds in (crates/horizon-prepare, crates/horizon-theme),
# every hour (a release the cooldown held goes out) and by hand, tools/release_train.py decides as for the game.
# every 10 minutes (a release waiting for merges to settle goes out) and by hand, tools/release_train.py decides as
# for the game.
# A release is launcher-vX.Y.Z: the patch after the last launcher tag, or the next minor when a merged pull
# request is labelled feature. The version is given to the build (HORIZON_LAUNCHER_VERSION): no bump commits.
# Never marked latest. Pushes to launcher branches only build. RELEASES_PAUSED=1 stops releases.
@@ -17,7 +18,7 @@ on:
- 'crates/horizon-theme/**'
- '.github/workflows/launcher.yml'
schedule:
- cron: '47 * * * *'
- cron: '7-59/10 * * * *'
workflow_dispatch:
inputs:
dry_run:
@@ -25,7 +26,7 @@ on:
type: boolean
default: true
force:
description: Release even without launcher changes, within the cooldown or while paused
description: Release even without launcher changes, before merges settle or while paused
type: boolean
default: false
+7 -6
View File
@@ -1,8 +1,9 @@
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.
# Automatic game releases (docs/release-flow.md). After every green `checks` run on main, every 10 minutes (so a
# release waiting for merges to settle goes out without another merge) and by hand, tools/release_train.py decides:
# a release when pull requests merged since the last one changed what players run and the newest merged 15 minutes
# ago (the oldest an hour ago, if merges never pause), 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.
@@ -14,7 +15,7 @@ on:
types: [completed]
branches: [main]
schedule:
- cron: '17 * * * *'
- cron: '2-59/10 * * * *'
workflow_dispatch:
inputs:
dry_run:
@@ -22,7 +23,7 @@ on:
type: boolean
default: true
force:
description: Release even without player-facing changes, within the cooldown or while paused
description: Release even without player-facing changes, before merges settle or while paused
type: boolean
default: false
permissions:
+8 -6
View File
@@ -73,7 +73,7 @@ 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.
to main, every 10 minutes (so a release waiting for merges to settle goes out without another merge), and by hand.
```mermaid
flowchart LR
@@ -83,7 +83,7 @@ flowchart LR
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 -- "player-facing PRs settled 15 min<br/>(or waiting 1 h), or release-now" --> build
decide -- otherwise --> wait(["wait"])
subgraph build["build, in parallel"]
linux["Linux x86_64<br/>GitHub ubuntu-22.04"]
@@ -104,8 +104,10 @@ commits) since the last **published** game release:
`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.
- It releases when at least one pull request counts and the newest of them merged at least 15 minutes ago, so a burst
of merges becomes one release; if merges never pause, it releases once the oldest has waited an hour. There is no
minimum time between releases: every settled player-facing change ships.
- A pull request labelled `release-now` (a crash or a blocker) releases at once.
- 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
@@ -116,7 +118,7 @@ commits) since the last **published** game release:
| 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 |
| `release-now` | Releases as soon as main's checks pass, without waiting for merges to settle |
| `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 |
@@ -193,7 +195,7 @@ and by hand; pushes to `launcher` and `launcher-*` branches only build.
- `tools/release_train.py decide --kind launcher` counts the pull requests merged since the last published
launcher release that changed those paths (not `launcher/links.json`, which the launcher reads from main, nor
tests or Markdown), with the same 3-hour cooldown, `release-now`, `skip-release` and `RELEASES_PAUSED`.
tests or Markdown), with the same settling rule (15 minutes, at most an hour), `release-now`, `skip-release` and `RELEASES_PAUSED`.
- The tag is `launcher-vX.Y.Z`: the patch after the last launcher tag, or the next minor (`X.Y+1.0`) when one of
those pull requests is labelled `feature`.
- No version-bump commits: the build gets the version in `HORIZON_LAUNCHER_VERSION`, which
+19 -13
View File
@@ -8,9 +8,10 @@ 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"):
def pr(number, title="Fix a thing", labels=(), paths=("crates/horizon-client/src/game.rs",), issues=(), author="ludovic111",
merged=dt.timedelta(hours=9)):
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}"}
"author": author, "url": f"https://github.com/ludovic111/horizon/pull/{number}", "merged_at": NOW - merged}
class ReleaseTrainTests(unittest.TestCase):
@@ -47,17 +48,19 @@ class ReleaseTrainTests(unittest.TestCase):
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")
minute = dt.timedelta(minutes=1)
decide = lambda prs, **kw: train.decision("game", prs, NOW, **kw)[0]
self.assertTrue(decide([pr(1, merged=16 * minute)]), "settled for the debounce")
self.assertFalse(decide([pr(1, merged=5 * minute)]), "merged moments ago")
self.assertFalse(decide([pr(1, merged=40 * minute), pr(2, merged=5 * minute)]), "a burst still merging")
self.assertTrue(decide([pr(1, merged=61 * minute), pr(2, merged=2 * minute)]), "merges that never pause still ship")
self.assertTrue(decide([pr(1, labels=["release-now"], merged=minute)]))
self.assertFalse(decide([pr(1, paths=[])]), "nothing players run")
self.assertFalse(decide([pr(1, labels=["skip-release"])]))
self.assertFalse(decide([pr(1, labels=["release-now", "skip-release"])]))
self.assertFalse(decide([pr(1, merged=5 * minute), pr(2, labels=["skip-release"], merged=minute)]), "the settled one waits for nothing")
self.assertFalse(decide([pr(1)], paused=True))
self.assertTrue(decide([], paused=True, force=True))
def test_notes(self):
prs = [pr(5, "Nether portals: vanilla timing and linking (fixes #94)", issues=[94]),
@@ -73,6 +76,9 @@ class ReleaseTrainTests(unittest.TestCase):
self.assertNotIn("#8", body)
self.assertIn("Thanks to @cosmic.", body)
self.assertLess(body.index("### New"), body.index("### Fixed"))
title, _ = train.notes("game", "v2026.10.15.2", [pr(9, "Horizon's mark", labels=["feature"]),
pr(10, "Game menus", labels=["feature"])], [])
self.assertEqual(title, "Horizon 2026.10.15.2: Game menus, Horizon's mark", "proper nouns keep their capital")
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)]
+21 -14
View File
@@ -6,8 +6,9 @@
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
player-facing paths (GAME_PATHS, LAUNCHER_PATHS) and the newest of them merged at least DEBOUNCE ago (a burst
of merges becomes one release), or the oldest at least MAX_WAIT ago (merges that never pause still ship), 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
@@ -29,7 +30,11 @@ import sys
ROOT = Path(__file__).resolve().parents[1]
REPO = os.environ.get("GITHUB_REPOSITORY", "ludovic111/horizon")
COOLDOWN = dt.timedelta(hours=3)
DEBOUNCE = dt.timedelta(minutes=15)
MAX_WAIT = dt.timedelta(hours=1)
# Kept as typed in release titles, where the clauses after the first are lowercased.
PROPER = {"Horizon", "Horizon's", "Minecraft", "Mojang", "Microsoft", "Java", "Xbox", "PlayStation", "Steam", "Windows",
"Linux", "LAN", "Kira", "Discord", "Wayland", "Hyprland", "F3", "GUI", "UI"}
EXPORTERS = "mods/horizon/src/test/java/dev/horizonlab/parity/"
# What players run. Documentation (*.md), tests, benchmarks and harness probes (examples/) never count.
@@ -119,7 +124,7 @@ def changed_paths(commit):
def pull_request(number):
data = gh_json("pr", "view", str(number), "--repo", REPO, "--json",
"number,title,url,labels,closingIssuesReferences,author")
"number,title,url,labels,closingIssuesReferences,author,mergedAt")
return {
"number": data["number"],
"title": data["title"].strip(),
@@ -127,6 +132,7 @@ def pull_request(number):
"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", ""),
"merged_at": dt.datetime.fromisoformat(data["mergedAt"].replace("Z", "+00:00")) if data.get("mergedAt") else None,
}
@@ -143,12 +149,12 @@ def last_release(releases, kind):
return max(ours, key=lambda release: tag_key(release["tag_name"]), default=None)
def decision(kind, prs, last_published, now, paused=False, force=False):
def decision(kind, prs, 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)."""
files it changed under "paths" (player-facing ones only) and when it merged ("merged_at")."""
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
merged = [pr["merged_at"] for pr in counted if pr.get("merged_at")]
if force:
return True, "started by hand with force"
if paused:
@@ -157,9 +163,9 @@ def decision(kind, prs, last_published, now, paused=False, force=False):
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)"
if merged and now - max(merged) < DEBOUNCE and now - min(merged) < MAX_WAIT:
wait = DEBOUNCE - (now - max(merged))
return False, f"{len(counted)} pull requests: waiting {wait.seconds // 60 + 1} more minutes for merges to settle"
return True, f"{len(counted)} pull requests changed what players run"
@@ -178,7 +184,9 @@ def summary(new, fixed, limit=72):
titles.append(title)
shown, text = [], ""
for title in titles:
title = title if not shown or not title[1:2].islower() else title[0].lower() + title[1:]
first = title.split(" ", 1)[0]
if shown and title[1:2].islower() and first not in PROPER:
title = title[0].lower() + title[1:]
candidate = ", ".join(shown + [title])
if shown and len(candidate) > limit - 20:
break
@@ -265,7 +273,7 @@ def main():
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("--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)")
args = parser.parse_args()
@@ -289,8 +297,7 @@ def main():
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)
release, reason = decision(args.kind, prs, 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)