docs: document the built-in platform folder aliases - #137

Description

Follows the platform slug work in rommapp/romm (unreleased, lands with the next tag). RomM now:

• resolves 138 folder names Batocera, RetroBat and ES-DE use (megadrive/, gamecube/, n3ds/, mame/, easyrpg/, ...) with no system.platforms binding,
• matches folder names case-insensitively on both sides of a binding,
• ships an rpg-maker platform for the easyrpg/ folder those frontends all carry.

The docs still told readers every platform folder has to be named after a slug, which is now wrong in the common case, and two of the remap examples were stale: gc is a built-in alias (so gc: "ngc" changes nothing), and psx: "ps" pointed at ps, which has never been a RomM slug (the PlayStation slug is psx, and ps/ is now an alias for it).

What changed

• platforms/supported-platforms.md: new Folder name aliases section, carrying a generated table plus the two caveats that bite — a binding always overrides an alias, and a folder name that is itself a slug never reaches the alias table.
• reference/configuration-file.md (system.platforms): reframed as "for folders RomM doesn't recognise or gets wrong", documented the case-insensitive matching and the binding → slug → alias order, replaced the two stale examples.
• getting-started/folder-structure.md, platforms/custom-platforms.md, about/faqs.md, troubleshooting/index.md, reference/glossary.md: pointed at the new section, ps → psx in the glossary.
• scripts/gen_platform_aliases.py + docs/resources/snippets/platform-aliases.md + romm-release-bump.yml: the alias table is generated and regenerates on the release bump, per review.

The generator

gen_platform_aliases.py fetches platform_aliases.py and platform_slugs.py from the pinned ref and parses them with ast, rather than shelling out to a romm-side script the way gen_platforms.py does. The alias table is a plain dict literal, so nothing needs importing, which means no romm checkout, no romm-side script and no cross-repo sequencing. It runs on bare stdlib. Output is 138 folder names over 103 platforms, grouped so folders sharing a target sit on one row and the many-to-one mappings stay visible.

The pin is 5.2.0, which predates the alias table, so the committed snippet was seeded with --ref master; the next bump regenerates it from the pin. Against a ref without the file the generator warns, leaves the committed table untouched and exits 0 — a missing alias table costs the alias table, not the whole bump PR (see the review thread; the earlier exit-1 behaviour would have taken the env-var and scheduled-task updates down with it).

Separately, and not fixed here: gen_platforms can't currently run in romm-release-bump.yml, because it needs ROMM_SRC and that job neither checks romm out nor sets it. Worth noting the workflow's 11 green runs all took the changed=false no-op path, so the regenerate step has never actually executed — this fires on the first real release bump. Flagged in the review thread; happy to fix in its own PR.

The atari800 case

Resolution checks the slug list before the alias table, so a folder name that already is a slug never reaches the aliases. ES-DE and Batocera use atari800/ for the whole Atari 8-bit family, but atari800 is RomM's slug for the Atari 800 alone, so it still needs an explicit binding. Both shipped example configs carry it.

Checks

• uv run mkdocs build --strict clean; the #folder-name-aliases anchor, its 7 inbound links, and the included snippet all verified in the built HTML
• uv run python -m scripts.check_redirects — all 46 targets exist
• prettier, markdownlint and yamllint clean under the repo configs; remaining markdownlint findings are pre-existing MD033 in untouched regions
• generator verified both ways: against 5.2.0 it warns and leaves the snippet byte-identical; against a ref carrying the table its output matches the committed snippet byte-for-byte
• spot-checked against the source: all 13 arcade folders match PLATFORM_FS_ALIASES exactly

Note on timing

This documents behaviour that is on master but not in a released tag yet. Merging now follows the filesystem.structure precedent (documented here Sep 10, feature landed Sep 8); happy to hold it until the next release instead if you'd rather the site only describe shipped versions.

AI assistance disclosure

Written with Claude Code. The alias table, resolution order, slug values and folder-name claims were each checked against backend/utils/platform_aliases.py and backend/utils/platform_slugs.py; a human should still review the wording.

Companion example-config tweak: rommapp/romm#4461 (merged).

🤖 Generated with Claude Code

https://claude.ai/code/session_0172ovkiqiK6JgEYCmi3uqe2