diff --git a/GOVERNANCE.md b/GOVERNANCE.md index d2f370a..884368e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -4,6 +4,8 @@ The `robocode-dev` organization owns this repository. Human review belongs to th Moderators maintain `bots/banned.json` through reviewed pull requests. A ban can cover an account or a bot and can be temporary. CI prevents a banned account from submitting and excludes disqualified bots from the generated catalog. Facts in the future `rumble-data` repository are never deleted merely because an entry is disqualified. +To retire bots from the Rumble, a moderator deletes their directories in a pull request that changes nothing else and approves its escalation. The publisher then marks their catalog entries `retired`. Retired entries stay as catalog history, and each name stays reserved for its owner without occupying an active slot. + Moderators resolve name-squatting, lost-account recovery, license complaints, and appeal requests case by case. A credible copyright complaint removes the bot from the working tree and disqualifies it pending resolution. ## Join the moderator team diff --git a/moderation/verify_catalog.py b/moderation/verify_catalog.py index 9a7577b..3718418 100644 --- a/moderation/verify_catalog.py +++ b/moderation/verify_catalog.py @@ -14,7 +14,7 @@ from moderation.assess import classify_paths from moderation.moderate import CONTEXT, GitHubError, api -from scripts.validate_bot import ValidationError, bot_directories, read_json, resolve_teams, validate_bot +from scripts.validate_bot import PLATFORMS, ValidationError, bot_directories, read_json, resolve_teams, validate_bot CATALOG_FILES = {"bots/index.json", "bots/owners.json"} APP_LOGIN = os.environ.get("RUMBLE_MODERATOR_LOGIN") or "tank-royale-rumble-moderator[bot]" @@ -30,17 +30,28 @@ def git(*args: str) -> str: return result.stdout.strip() -def source_paths(number: int) -> list[str]: - paths = [] +def source_files(number: int) -> list[dict]: + items = [] page = 1 while True: files = api("GET", f"pulls/{number}/files?per_page=100&page={page}") - paths.extend(item["filename"] for item in files) + items.extend(files) if len(files) < 100: - return paths + return items page += 1 +def removed_bot_directories(files: list[dict]) -> set[str]: + """Return the bot directories a source PR only deleted files from, or an empty set otherwise.""" + directories: set[str] = set() + for item in files: + parts = item["filename"].split("/") + if item.get("status") != "removed" or len(parts) < 4 or parts[0] != "bots" or parts[1] not in PLATFORMS: + return set() + directories.add("/".join(parts[:3])) + return directories + + def unpublished_bot_paths(root: Path) -> set[str]: catalog = read_json(root / "bots" / "index.json") active = {entry["name"]: entry for entry in catalog["bots"] if entry["status"] == "active"} @@ -70,11 +81,20 @@ def verify(number: int, source_number: int) -> tuple[str, str]: if (source["merged_at"] is None or source["base"]["ref"] != "main" or not re.fullmatch(r"[A-Za-z0-9-]+", source["user"]["login"])): raise VerificationError("Source submission is not a merged main PR") - source_directory = classify_paths(source_paths(source_number))[0] - if source_directory is None: - raise VerificationError("Source PR did not change exactly one bot directory") + files = source_files(source_number) + removed = removed_bot_directories(files) + if removed: + # A moderator's removal PR retires bots; it attributes no new ownership. + if any(Path(directory).exists() for directory in removed): + raise VerificationError("A removed bot directory still exists on main") + expected_pending: set[str] = set() + else: + source_directory = classify_paths([item["filename"] for item in files])[0] + if source_directory is None: + raise VerificationError("Source PR did not change exactly one bot directory") + expected_pending = {source_directory} pending_paths = unpublished_bot_paths(Path.cwd()) - if pending_paths != {source_directory}: + if pending_paths != expected_pending: raise VerificationError(f"Other unpublished bot changes need ownership review: {sorted(pending_paths)}") statuses = api("GET", f"commits/{source['head']['sha']}/statuses?per_page=100") moderation = next((item for item in statuses if item["context"] == CONTEXT), None) @@ -82,7 +102,7 @@ def verify(number: int, source_number: int) -> tuple[str, str]: or (moderation.get("creator") or {}).get("login") != APP_LOGIN): raise VerificationError("Source bot has no successful moderator App status") try: - git("diff", "--quiet", source["head"]["sha"], base, "--", source_directory) + git("diff", "--quiet", source["head"]["sha"], base, "--", *sorted(removed or expected_pending)) except subprocess.CalledProcessError as error: raise VerificationError("Merged source bot content differs from current main") from error subprocess.run(["git", "fetch", "--no-tags", "origin", f"+refs/pull/{number}/head:refs/remotes/origin/catalog-verify"], check=True) diff --git a/scripts/validate_bot.py b/scripts/validate_bot.py index cb386bc..d2377a8 100644 --- a/scripts/validate_bot.py +++ b/scripts/validate_bot.py @@ -320,6 +320,8 @@ def generated_catalog(bots: list[Bot], root: Path, owner: str, generated_at: dat for owner_id, names in records.items(): owner_record = owners.setdefault(owner_id, {"accounts": [owner_id], "bots": set()}) owner_record["bots"].update(names) + current_by_name = {bot.name: bot for bot in bots} + # A removed bot's name stays reserved for its owner, but it no longer occupies an active slot. owner_data = { "schemaVersion": 1, "owners": [ @@ -327,23 +329,24 @@ def generated_catalog(bots: list[Bot], root: Path, owner: str, generated_at: dat "ownerId": owner_id, "accounts": owner_record["accounts"], "bots": sorted(owner_record["bots"]), - "activeSlots": len(owner_record["bots"]), + "activeSlots": len(owner_record["bots"] & current_by_name.keys()), } for owner_id, owner_record in sorted(owners.items()) ], } today = generated_at.date().isoformat() - current_by_name = {bot.name: bot for bot in bots} history = [] for entry in existing_catalog.get("bots", []): current = current_by_name.get(entry.get("name")) - if current is not None and entry.get("version") != current.config["version"] and entry.get("status") == "active": - history.append(entry | {"status": "superseded"}) + if entry.get("status") != "active": + history.append(entry) # superseded, retired and disqualified entries stay as history elif current is None: - history.append(entry) + history.append(entry | {"status": "retired"}) # the bot's directory was removed + elif entry.get("version") != current.config["version"]: + history.append(entry | {"status": "superseded"}) active = [] for bot in sorted(bots, key=lambda item: item.name.casefold()): - previous = next((entry for entry in existing_catalog.get("bots", []) if entry.get("name") == bot.name and entry.get("version") == bot.config["version"]), None) + previous = next((entry for entry in existing_catalog.get("bots", []) if entry.get("name") == bot.name and entry.get("version") == bot.config["version"] and entry.get("status") == "active"), None) team_members = list(bot.team_member_identities) active.append({"name": bot.name, "version": bot.config["version"], "platform": bot.platform, "path": bot.directory.relative_to(root).as_posix(), "sourceHash": bot.source_hash, "owner": owner_by_bot.get(bot.name, owner), "authors": bot.config["authors"], "addedAt": previous.get("addedAt", today) if previous else today, "status": "active", "teamMembers": team_members}) catalog = {"schemaVersion": 1, "generatedAt": generated_at.replace(microsecond=0).isoformat().replace("+00:00", "Z"), "commit": os.environ.get("GITHUB_SHA", "local"), "bots": history + active} diff --git a/tests/test_moderation.py b/tests/test_moderation.py index 8248c18..a027b67 100644 --- a/tests/test_moderation.py +++ b/tests/test_moderation.py @@ -296,6 +296,69 @@ def fake_git(*args): with self.assertRaisesRegex(verify_catalog.VerificationError, "no successful moderator App status"): verify_catalog.verify(12, 7) + def test_removal_only_source_retires_bots_without_new_ownership(self): + base = "c" * 40 + generated_at = datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z") + catalog = {"bots/index.json": json.dumps({"generatedAt": generated_at}) + "\n", "bots/owners.json": "{}\n"} + source = {"merged_at": generated_at, "base": {"ref": "main"}, "head": {"sha": "d" * 40}, + "user": {"login": "moderator"}} + statuses = [{"context": moderate.CONTEXT, "state": "success", "creator": {"login": verify_catalog.APP_LOGIN}}] + files = [{"filename": "bots/python/Orbit/Orbit.json", "status": "removed"}, + {"filename": "bots/java/RumbleTestScout/RumbleTestScout.sh", "status": "removed"}] + existing: set[str] = set() + pending: set[str] = set() + compared = [] + + def fake_api(method, path, payload=None): + if path == "pulls/12": + return self.pr + if path == "pulls/7": + return source + if path.startswith("pulls/7/files"): + return files + if path == f"commits/{'d' * 40}/statuses?per_page=100": + return statuses + raise AssertionError(path) + + def fake_git(*args): + if args in (("rev-parse", "HEAD"), ("rev-parse", f"{SHA}^")): + return base + if args == ("rev-parse", "refs/remotes/origin/catalog-verify"): + return SHA + if args[:2] == ("diff", "--name-only"): + return "bots/index.json\nbots/owners.json" + if args[0] == "show": + return catalog[args[1].split(":", 1)[1]].strip() + if args[:2] == ("diff", "--quiet"): + compared.append(args[4:]) + return "" + raise AssertionError(args) + + with patch.dict("os.environ", {"GITHUB_REPOSITORY": "robocode-dev/rumble-bots"}), patch.object( + verify_catalog, "api", side_effect=fake_api + ), patch.object(verify_catalog, "unpublished_bot_paths", side_effect=lambda root: pending), patch.object( + verify_catalog, "git", side_effect=fake_git), patch.object( + verify_catalog.subprocess, "run", return_value=CompletedProcess([], 0, "", "") + ), patch.object(verify_catalog.Path, "exists", autospec=True, side_effect=lambda path: path.as_posix() in existing + ), patch.object(verify_catalog.Path, "read_text", autospec=True, + side_effect=lambda path, encoding=None: catalog[path.as_posix()]): + self.assertEqual((SHA, base), verify_catalog.verify(12, 7)) + self.assertEqual([("--", "bots/java/RumbleTestScout", "bots/python/Orbit")], compared) + + existing.add("bots/python/Orbit") + with self.assertRaisesRegex(verify_catalog.VerificationError, "still exists on main"): + verify_catalog.verify(12, 7) + existing.clear() + + pending.add("bots/java/Other") + with self.assertRaisesRegex(verify_catalog.VerificationError, "Other unpublished bot changes"): + verify_catalog.verify(12, 7) + pending.clear() + + files.append({"filename": "bots/java/Other/Other.json", "status": "added"}) + with self.assertRaisesRegex(verify_catalog.VerificationError, "exactly one bot directory"): + verify_catalog.verify(12, 7) + if __name__ == "__main__": unittest.main() diff --git a/tests/test_validate_bot.py b/tests/test_validate_bot.py index c5f7772..4bb96a7 100644 --- a/tests/test_validate_bot.py +++ b/tests/test_validate_bot.py @@ -15,6 +15,7 @@ TEST_OWNER = "flemming-n-larsen" sys.path.insert(0, str(REPOSITORY / "scripts")) from validate_bot import tree_hash # noqa: E402 +from test_templates import copy_template # noqa: E402 class ValidatorIntegrationTests(unittest.TestCase): @@ -43,6 +44,18 @@ def setUp(self) -> None: if bot_directory.is_dir() and relative_path not in owned_paths: shutil.rmtree(bot_directory) + # The tests need a published Python bot. Build it from the official template rather than + # depend on a live Python bot, which may be retired from the Rumble. + shutil.rmtree(bots_root / "python", ignore_errors=True) + owned_entries = [entry for entry in owned_entries if not entry["path"].startswith("bots/python/")] + orbit = copy_template(self.root, "python", "Orbit") + orbit_config = json.loads((orbit / "Orbit.json").read_text(encoding="utf-8")) + owned_entries.append({"name": "Orbit", "version": orbit_config["version"], "platform": "Python", + "path": "bots/python/Orbit", "sourceHash": tree_hash(orbit), "owner": TEST_OWNER, + "authors": orbit_config["authors"], "addedAt": "2026-10-21", "status": "active", + "teamMembers": []}) + owner_record["bots"] = sorted(set(owner_record["bots"]) | {"Orbit"}) + catalog["bots"] = owned_entries owners["owners"] = [owner_record] catalog_path.write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8") @@ -139,8 +152,8 @@ def test_source_change_without_version_increase_is_rejected(self) -> None: self.assertIn("without increasing its version", result.stderr) def test_version_increase_supersedes_the_previous_catalog_entry(self) -> None: - # SpinBot has no team member depending on it, unlike Orbit (OrbitVector) and - # Corners/Crazy (CornersCrazy), so bumping its version here can't break a team identity. + # SpinBot has no team member depending on it, unlike Corners/Crazy (CornersCrazy), + # so bumping its version here can't break a team identity. self.assertEqual(0, self.run_validator("--generate").returncode) config_path = self.root / "bots" / "java" / "SpinBot" / "SpinBot.json" config = json.loads(config_path.read_text(encoding="utf-8")) @@ -150,6 +163,31 @@ def test_version_increase_supersedes_the_previous_catalog_entry(self) -> None: catalog = json.loads((self.root / "bots" / "index.json").read_text(encoding="utf-8")) spinbot = [entry for entry in catalog["bots"] if entry["name"] == "SpinBot"] self.assertEqual(["superseded", "active"], [entry["status"] for entry in spinbot]) + # Later regenerations keep the history instead of dropping the superseded entry. + self.assertEqual(0, self.run_validator("--generate").returncode) + catalog = json.loads((self.root / "bots" / "index.json").read_text(encoding="utf-8")) + spinbot = [entry for entry in catalog["bots"] if entry["name"] == "SpinBot"] + self.assertEqual([("1.0.0", "superseded"), ("1.0.4", "active")], + [(entry["version"], entry["status"]) for entry in spinbot]) + + def test_removed_bot_is_retired_and_its_name_stays_reserved(self) -> None: + self.assertEqual(0, self.run_validator("--generate").returncode) + shutil.rmtree(self.root / "bots" / "java" / "SpinBot") + + for _ in range(2): # the retired entry also survives a later regeneration + result = self.run_validator("--generate") + self.assertEqual(0, result.returncode, result.stderr) + catalog = json.loads((self.root / "bots" / "index.json").read_text(encoding="utf-8")) + self.assertEqual([("1.0.0", "retired")], [(entry["version"], entry["status"]) + for entry in catalog["bots"] if entry["name"] == "SpinBot"]) + + owners = json.loads((self.root / "bots" / "owners.json").read_text(encoding="utf-8")) + record = owners["owners"][0] + self.assertIn("SpinBot", record["bots"]) + active = [entry for entry in catalog["bots"] if entry["status"] == "active"] + self.assertEqual(len(active), record["activeSlots"]) + self.add_java_bot("SpinBot") + self.assertIn("belongs to owner", self.run_validator(owner="alice").stderr) def test_new_bot_from_another_owner_ignores_unchanged_catalog_entries(self) -> None: self.assertEqual(0, self.run_validator("--generate").returncode)