horizon-airdef/tools/release_channels.py

#!/usr/bin/env python3
"""Promotes Horizon's beta game releases to stable once a day (.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): launchers on the Alpha channel install it at once.
Stable moves once a day, at PROMOTE_AT (20:00 UTC). 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 had been out PROMOTE_AFTER (6 hours) at the day's promotion time, so every run until the next one picks the
  same beta and a run GitHub starts late (or a second try) never promotes twice; 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 (30 hours: past one daily promotion it
was due for, so a normal day never trips it), 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 subprocess
import sys
import tempfile

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from tools.release_train import is_game_tag, tag_key  # noqa: E402  (vYYYY.MM.DD[.N] and v0.2.0: docs/versioning.md)

REPO = os.environ.get("GITHUB_REPOSITORY", "ludovic111/horizon")
PROMOTE_AFTER = dt.timedelta(hours=6)
# The daily promotion (21:00 in Paris in winter time, 22:00 in summer); promote.yml's schedule runs just after it.
PROMOTE_AT = dt.time(20, 0)
SMOKE_ASSET = "smoke-test.json"
BLOCKER = "release-blocker"
STALL_AFTER = dt.timedelta(hours=30)
STALLED = "Promotion to stable has stalled"


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 promotion_time(now):
    """The last daily promotion time (PROMOTE_AT, UTC) at or before now."""
    now = now.astimezone(dt.timezone.utc)
    at = dt.datetime.combine(now.date(), PROMOTE_AT, dt.timezone.utc)
    return at if at <= now else at - dt.timedelta(days=1)


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']}")
    ready = parse_time(release["published_at"]) + PROMOTE_AFTER
    if not by_hand and ready > promotion_time(now):
        due = promotion_time(ready)
        due += dt.timedelta(days=1 if due < ready else 0)
        reasons.append(f"it had not been out {PROMOTE_AFTER.seconds // 3600} h at a daily promotion yet: "
                       f"the one at {due:%Y-%m-%d %H:%M} UTC takes it")
    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 is_game_tag(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']} had been out {PROMOTE_AFTER.seconds // 3600} h at the daily promotion, " \
                            "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 is_game_tag(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 is_game_tag(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=<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 wait for the daily promotion)")
    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)
    now = now if now.tzinfo else now.replace(tzinfo=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())