diff --git a/docs/version-ports.md b/docs/version-ports.md index 15d77b056..5271128f2 100644 --- a/docs/version-ports.md +++ b/docs/version-ports.md @@ -245,11 +245,27 @@ summary counts pass / oracle / fail / newly failing. files and harnesses, the data-diff excerpts that concern it, and the local path of its source diffs. 3. Everything regenerated cleanly, so the reader knows what not to look at. -`version_port.py publish` opens one GitHub issue per item of ranks 1 to 3 (labels `version-port` and -`port-NEW`, title `[NEW] : `; an open issue with that title is updated instead), with the structured -diff attached (names, signatures, data-report diffs, harness output; no decompiled code), and a Kira card per issue -(`card_add` with the issue URL, column `todo`) so contributors and agents can claim them. Rank 4 and 5 go into one -tracking issue. +`version_port.py publish OLD NEW` (`tools/port_publish.py`) files the report as GitHub issues. **It is a dry run +by default**: it prints every issue it would create or update and the first bodies (`--show N`; `--check-github` +reads the open issues and labels, read-only, to tell creates from updates). `--yes` does it; the first `--yes` run +and the `version-port` label are Ludovic's call. + +- **One issue per item** of rank 1, of rank 2 when a harness newly fails on NEW (or its oracle no longer compiles), + and of rank 3 when Horizon's comments name one of the changed methods: title `[NEW] `, labels + `version-port` and `port-NEW`. An open issue with the same title is updated, and only its generated part + (between `` markers) is replaced: what people wrote around it stays. +- **One tracking issue**, `[NEW] Port to Minecraft NEW`: the facts, the harness counts, a checklist of the item + issues (made after them, so it has their numbers), and every other item: rank-2 leads no harness confirmed, rank-3 + classes Horizon names but none of whose changed methods, new content, unported changes. +- **Kira**: the board already shows every open issue as a card in To do, with its labels, so contributors and agents + claim them there (`task_claim`); `publish` adds one Kira card for the port itself, linking the tracking issue + (`~/code/horizon-parity/tools/kira.mjs card_add`, skipped if the board has it). +- **No decompiled code, ever**: bodies hold names and signatures only (vanilla classes, methods with their JVM + descriptors, fields, packets, registry entries, harness names, javac's one-line errors about Horizon's own oracles, + Horizon paths, and the local path of the diff). Every vanilla-derived string is quoted, and `assert_no_code` + refuses a body with a code block, or a line or quoted span that reads like Java (declarations, statements, braces). + +For 26.2 → 26.3 the dry run would file 48 issues (5 of rank 1, 43 of rank 3) and the tracking issue. ### The switch and the release @@ -357,6 +373,7 @@ python3 tools/version_port.py diff 26.3 26.4 # summary; the full diff in python3 tools/version_port.py regen 26.4 # ports/26.4 on port/26.4: pinned, every table regenerated python3 tools/version_port.py report 26.3 26.4 [--results .local/parity-runner/state.json] # report.md, report.json python3 tools/version_port.py harnesses 26.4 --baseline .local/parity-runner/state.json # in ports/26.4 +python3 tools/version_port.py publish 26.3 26.4 # dry run: the issues it would file (--yes files them) python3 tools/version_port.py port 26.4 # prepare both, diff, regen, report python3 tools/version_port.py gc # keep the pinned version and the newest two others python3 tools/vanilla_map.py versions/26.3/classes.json net.minecraft.world.food.FoodData # its Rust files and harnesses @@ -372,4 +389,5 @@ python3 tools/vanilla_map.py versions/26.3/classes.json net.minecraft.world.food | Tools read the version from the lock (`lab.VERSION`, `lab.GAME`, `lab.RESOURCES`, `lab.version_info()`) | done | | `regen` (`tools/port_regen.py`): candidate worktree, its `.local/`, the generators' classes decompiled alone, every generator, `regen.json` in the report | done | | Candidate harness run (`tools/port_harness.py`, `harnesses`): horizon-prepare with sounds, every harness, pass / oracle / fail, newly failing against a baseline, in the report | done | -| `publish`, launchd agent | later | +| `publish` (`tools/port_publish.py`): dry run by default, issues, tracking issue, Kira card | done (never run with `--yes`) | +| launchd agent | later | diff --git a/tests/test_port_publish.py b/tests/test_port_publish.py new file mode 100644 index 000000000..921505901 --- /dev/null +++ b/tests/test_port_publish.py @@ -0,0 +1,98 @@ +from pathlib import Path +import unittest +from unittest import mock + +from tools import port_publish as publish + +DIFF = {"classes": {"changed": {"net/minecraft/world/food/FoodData": { + "methods": {"added": [], "removed": [], "changed": ["tick(Lnet/minecraft/server/level/ServerPlayer;)V"]}, + "fields": {"added": ["exhaustionLevel F"], "removed": [], "changed": []}}}}} + + +def items(): + return [ + {"rank": 1, "kind": "protocol", "title": "Protocol: packets play/clientbound +1 -0 ~3", + "files": ["crates/horizon-protocol/src/ids.rs"], "details": {"packets": {"play/clientbound": { + "added": {"minecraft:punch": 3}, "removed": {}, "renumbered": {"minecraft:x": [1, 2]}}}}}, + {"rank": 2, "kind": "rerun", "title": "crates/w/src/food.rs: 1 vanilla classes changed", "harnesses": ["food"], + "failed": [], "classes": {}}, + {"rank": 2, "kind": "harness-failed", "title": "Harness light: fails on 26.4", "failed": ["light"], + "oracle": [], "harnesses": ["light"]}, + {"rank": 3, "kind": "unproved", "title": "crates/w/src/food.rs: 1 vanilla classes changed (1 methods, 1 named)", + "files": ["crates/w/src/food.rs"], "classes": {"net/minecraft/world/food/FoodData": { + "methods": 1, "named": ["tick"], "removed": False}}}, + {"rank": 3, "kind": "unproved", "title": "crates/c/src/sky.rs: 1 vanilla classes changed (2 methods, 0 named)", + "classes": {"net/minecraft/client/Sky": {"methods": 2, "named": [], "removed": False}}}, + {"rank": 4, "kind": "content", "title": "New block: 2 entries", "entries": ["minecraft:a", "minecraft:b"]}, + ] + + +REPORT = {"old": "26.3", "new": "26.4", "summary": {"facts": {"protocol_version": [777, 780]}}, "items": items()} + + +class PublishTests(unittest.TestCase): + def test_which_items_get_an_issue(self): + self.assertEqual([publish.published(i) for i in items()], [True, False, True, True, False, False]) + + def test_body_has_names_and_signatures_only(self): + text = publish.body(items()[3], REPORT, DIFF, Path.home() / "code/horizon-parity/versions/diff-26.3-26.4") + self.assertIn("`net.minecraft.world.food.FoodData`: 1 methods changed; Horizon's comments name tick", text) + self.assertIn("methods changed: `tick(Lnet/minecraft/server/level/ServerPlayer;)V`", text) + self.assertIn("fields added: `exhaustionLevel F`", text) + self.assertIn("`~/code/horizon-parity/versions/diff-26.3-26.4`", text) + self.assertTrue(text.startswith(publish.START) and text.rstrip().endswith(publish.END)) + + def test_refuses_code(self): + for line in ["```java\nint x = 1;\n```", " return this.foodLevel;", "public void tick(Player player) {", + "- `if (x) { y(); }`", "import net.minecraft.world.food.FoodData;"]: + with self.assertRaises(ValueError, msg=line): + publish.assert_no_code(line) + publish.assert_no_code("- `(Lnet/minecraft/core/RegistryAccess;Lnet/minecraft/world/Foo;)V`, `a()V`") + publish.assert_no_code("- `ParityData.java:45: cannot find symbol: variable WORLD (class RegistryLayer)`") + + def test_update_keeps_what_people_wrote(self): + existing = f"Notes from a contributor.\n{publish.START}\nold\n{publish.END}\nMore notes." + self.assertEqual(publish.merged(existing, f"{publish.START}\nnew\n{publish.END}\n"), + f"Notes from a contributor.\n{publish.START}\nnew\n{publish.END}\nMore notes.") + self.assertEqual(publish.merged("no markers", "generated"), "generated") + + def test_plan_creates_updates_and_tracks(self): + name = "[26.4] Protocol: packets play/clientbound +1 -0 ~3" + actions = publish.plan(REPORT, DIFF, Path("/tmp/d"), {name: (12, "old body")}) + self.assertEqual([(a, t) for a, t, _, _ in actions], [ + ("update", name), ("create", "[26.4] Harness light: fails on 26.4"), + ("create", "[26.4] crates/w/src/food.rs: 1 vanilla classes changed (1 methods, 1 named)"), + ("create", "[26.4] Port to Minecraft 26.4")]) + tracking = actions[-1][2] + self.assertIn("- [ ] #12 " + name, tracking) + self.assertIn("- rank 4: New block: 2 entries", tracking) + + def test_apply_lists_the_new_issue_numbers_in_the_tracking_issue(self): + calls = [] + + def gh(*args): + calls.append(args) + if args[:2] == ("label", "list"): + return "version-port\nport-26.4\n" + if args[:2] == ("issue", "create"): + return f"https://github.com/o/r/issues/{100 + sum(1 for c in calls if c[:2] == ('issue', 'create'))}\n" + return "" + + actions = publish.plan(REPORT, DIFF, Path("/tmp/d"), {}) + with mock.patch.object(publish, "gh", side_effect=gh): + bodies = {} + real = publish.issue + + def issue(action, name, text, number, new): + bodies[name] = text + return real(action, name, text, number, new) + + with mock.patch.object(publish, "issue", side_effect=issue): + urls = publish.apply(actions, REPORT, {}) + self.assertEqual(urls["[26.4] Port to Minecraft 26.4"], "https://github.com/o/r/issues/104") + self.assertIn("- [ ] #101 [26.4] Protocol", bodies["[26.4] Port to Minecraft 26.4"]) + self.assertFalse([c for c in calls if c[:2] == ("label", "create")]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/port_publish.py b/tools/port_publish.py new file mode 100644 index 000000000..3541c0f97 --- /dev/null +++ b/tools/port_publish.py @@ -0,0 +1,251 @@ +#!/usr/bin/env python3 +"""File a port report's work items as GitHub issues (docs/version-ports.md, "The port report"). + +Used through `version_port.py publish OLD NEW [--yes]`. A dry run by default: it prints what it would create or +update; --yes does it (labels, issues, the Kira card). The maintainer approves the first --yes run and the +`version-port` label. + +- One issue per work item of rank 1, of rank 2 when a harness newly fails on NEW (or its oracle no longer + compiles), and of rank 3 when Horizon's comments name a changed method, titled "[NEW] " and labelled `version-port` and `port-NEW`. An open issue with + the same title is updated: only the generated part of its body (between the markers) is replaced, so what people + wrote around it stays. +- One tracking issue, "[NEW] Port to Minecraft NEW", listing those issues and every other item (rank-2 leads no + harness confirmed, new content, unported changes). +- Kira shows every open issue as a card in To do, labelled, so contributors and agents can claim them there; publish + adds one Kira card for the port itself, linking the tracking issue. + +Bodies hold names and signatures only: vanilla classes, methods with their descriptors, fields, registry entries, +packets, harness names, javac's one-line errors (about Horizon's own oracles), Horizon file paths and the local +path of the diff. Never decompiled code: `assert_no_code` refuses a body with a line that reads like Java source. +""" + +import json +import os +from pathlib import Path +import re +import subprocess +import tempfile + +try: + from . import port_report +except ImportError: + import port_report + +LABEL = "version-port" +START, END = "", "" +KIRA = Path(os.environ.get("HORIZON_KIRA", Path.home() / "code/horizon-parity/tools/kira.mjs")) +RANKS = {1: "blocks the switch", 2: "proved by a harness", 3: "ported, no harness", 4: "new content", + 5: "not ported"} +# A line of Java source: a declaration, a statement, an import (what decompiled code looks like). +CODE = re.compile(r"^\s*(?:(?:public|private|protected|static|final|abstract)\s+[\w<>\[\], ]+[\s(]" + r"|(?:return|throw|import|package)\s+\S|(?:if|for|while|switch)\s*\(|[}{]\s*$)|;\s*$") +# Inside backticks: names, JVM descriptors (`m(Lx/Y;I)V`, no spaces) and javac's one-line errors, never braces, +# statements or assignments. +QUOTED_CODE = re.compile(r"[{}]|;\s+\S|\s=\s|\breturn\s|\bnew\s+[A-Z]") + + +def published(item): + """Whether an item gets its own issue: rank 1; rank 2 when a harness newly fails; rank 3 when Horizon's + comments name one of the changed methods (the others are leads, listed in the tracking issue).""" + if item["rank"] == 3: + return any(info.get("named") for info in (item.get("classes") or {}).values()) + return item["rank"] == 1 or (item["rank"] == 2 and bool(item.get("failed"))) + + +def title(new, item): + return f"[{new}] {item['title']}"[:240] + + +def signatures(name, change, limit=20): + """A changed class's members by name and descriptor (from the class index: no code).""" + lines = [] + for kind in ("methods", "fields"): + for label in ("added", "removed", "changed"): + members = change.get(kind, {}).get(label, []) + if members: + shown = ", ".join(f"`{m}`" for m in members[:limit]) + more = f" (+{len(members) - limit})" if len(members) > limit else "" + lines.append(f" - {kind} {label}: {shown}{more}") + return lines + + +def body(item, report, diff, store_path, limit=25): + """The generated part of an item's issue.""" + old, new = report["old"], report["new"] + lines = [START, f"Minecraft {old} → {new}, rank {item['rank']} ({RANKS[item['rank']]}), from " + f"`tools/version_port.py report {old} {new}` (docs/version-ports.md).", ""] + if item.get("command"): + lines.append(f"Run: `{item['command']}`") + if item.get("compile_errors"): + lines += ["javac, against " + new + ":", *(f"- `{e}`" for e in item["compile_errors"])] + if item.get("failed"): + lines.append(f"Harnesses failing on {new}: " + ", ".join(f"`{h}`" for h in item["failed"]) + + (f" (oracle no longer compiles: {', '.join(item['oracle'])})" if item.get("oracle") else "")) + if item.get("harnesses"): + lines.append("Harnesses that prove it: " + ", ".join(f"`{h}`" for h in item["harnesses"][:limit])) + if item.get("files"): + lines.append("Horizon: " + ", ".join(f"`{f}`" for f in item["files"][:limit]) + + (f" (+{len(item['files']) - limit})" if len(item["files"]) > limit else "")) + classes = item.get("classes") + if isinstance(classes, dict): + lines += ["", "Vanilla classes (names and signatures):"] + changed = (diff.get("classes") or {}).get("changed", {}) + for name, info in list(classes.items())[:limit]: + what = "removed" if info["removed"] else f"{info['methods']} methods changed" + named = f"; Horizon's comments name {', '.join(info['named'])}" if info["named"] else "" + lines.append(f"- `{name.replace('/', '.')}`: {what}{named}") + lines += signatures(name, changed.get(name, {})) + elif classes: + lines.append("New classes: " + ", ".join(f"`{c.replace('/', '.')}`" for c in classes[:limit])) + if item.get("entries"): + lines.append("Entries: " + ", ".join(f"`{e}`" for e in item["entries"][:limit])) + details = item.get("details", {}) + if item["kind"] == "protocol": + for flow, change in details["packets"].items(): + lines.append(f"- {flow}: added {', '.join(change['added']) or 'none'}; removed " + f"{', '.join(change['removed']) or 'none'}; {len(change['renumbered'])} renumbered") + for key in ("schemas", "fixes"): + if details.get(key): + lines.append(f"{key.capitalize()}: " + ", ".join(f"`{port_report.short(n)}`" for n in details[key])) + if item["kind"] == "components": + types = details["types"] + lines += [f"Types {label}: " + ", ".join(f"`{t}`" for t in types.get(label, [])) + for label in ("added", "removed") if types.get(label)] + lines += [f"- `{c}`: " + ", ".join(f"{k} on {n} items" for k, n in counts.items() if n) + for c, counts in sorted(details["items"].items(), key=lambda kv: -sum(kv[1].values()))[:limit]] + if item["kind"] == "facts": + lines += [f"- {key}: {a} → {b}" for key, (a, b) in details.items()] + where = str(store_path).replace(str(Path.home()), "~") + lines += ["", f"The full diff stays on the maintainer's machine (`{where}`), with the vanilla files it was built " + "from: they are never published.", END] + text = "\n".join(lines) + "\n" + assert_no_code(text) + return text + + +def assert_no_code(text): + """Every name and signature goes in `backticks`, one line at most; what is left must not read like Java.""" + if "```" in text: + raise ValueError("Refusing to publish a code block") + for line in text.splitlines(): + if any(QUOTED_CODE.search(span) for span in re.findall(r"`([^`]*)`", line)): + raise ValueError(f"Refusing to publish a quoted span that reads like source code: {line[:120]!r}") + prose = re.sub(r"`[^`]*`", "", line).strip(" -*,;:()") + if line.startswith("