Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 30 additions & 10 deletions moderation/verify_catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]"
Expand All @@ -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"}
Expand Down Expand Up @@ -70,19 +81,28 @@ 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)
if (moderation is None or moderation["state"] != "success"
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)
Expand Down
15 changes: 9 additions & 6 deletions scripts/validate_bot.py
Original file line number Diff line number Diff line change
Expand Up @@ -320,30 +320,33 @@ 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": [
{
"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}
Expand Down
63 changes: 63 additions & 0 deletions tests/test_moderation.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
42 changes: 40 additions & 2 deletions tests/test_validate_bot.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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"))
Expand All @@ -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)
Expand Down
Loading