docs: 5.3 release documentation - #139
Merged
Merged
Conversation
Pins `sources.toml` at the 5.3 branch point so the environment-variable, scheduled-task and platform tables carry the release's contents. `gen_scheduled_tasks.py` read the task list out of `startup.py`'s `.init()` calls and `endpoints/tasks.py`'s `manual_tasks`. Upstream #4274 moved scheduling to RQ, and both now live in one `backend/tasks/registry.py` as the `SCHEDULED_TASKS` and `MANUAL_TASKS` dicts, so the parser reads those instead and keeps the registries' own order. The table picks up the recommendations index and the missing firmware cleanup. `UPC_LOOKUP_*` and the recommendation task's two variables are not in upstream's `env.template` yet (rommapp/romm#4467), so the two tables here were generated against that branch. They regenerate identically once it lands. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Streaming is now one webstation container serving every platform you point at it, so `streaming.containers` takes one entry per container with a `platforms` map, and the container's own keys are the defaults for every platform it serves. Both the guide and the schema reference still described one entry per emulator. Also covers what the release adds around that: container pools, the in-game save archive, the memory card library, live disc swap and the disc a state remounts, joinable sessions, admin desktop sessions and the container fleet, and `STREAMING_LAUNCH_TIMEOUT`. The supported platform table is rebuilt from the broker's capability tables, which now reach well past the original three emulators. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Steam covers the `win`, `linux` and `mac` platforms with no API key, and the three demoscene databases cover productions on platforms RomM already supports, matched by production id from a filename tag, a bare id, or a production URL. Also refreshes what had drifted around them: the `scan.priority` defaults (artwork has carried its own order for a while, led by the two artwork-only sources), the provider slug table, the filename tag list, and `HASHEOUS_API_URL` for a self-hosted Hasheous. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…kebox Four features with no page at all. Each covers what the feature is, how it reaches the library, the permissions and env vars behind it, and its endpoints: - Physical games, entries with no file on disk, added by name or by barcode through the `UPC_LOOKUP_*` lookup, and what having no file excludes them from. - Walkthroughs, documents in a `walkthrough/` folder next to manuals, with the GameFAQs importer's plain-text-only contract and per-user reading progress. - Recommendations, the library-relative similarity index behind both Similar games and the personalised feed, and the nightly task that builds it. - Jukebox, the soundtrack player over `soundtrack/` folders, its facets, generated mixes and playlists. Folder Structure's multi-file subfolder list was three folders short and is now a table, since `walkthrough` and `soundtrack` are where two of these pages start. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…rries PICO-8 carts (`.p8` and `.p8.png`) play on FAKE-08, a native player rather than a libretro core, with a `.p8.png` cart's own PNG used as its cover art. Image Variants claimed the slim image fetches "the browser emulator runtimes" from a CDN, but only EmulatorJS and `js-dos` have a fallback. Ruffle and PICO-8 are bundled or nothing, so the page now lists all four. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- `filesystem.skip_title_id_extraction` and `embed_switch_title_ids`, which the scan's title-id read is gated on. - `emulatorjs.default_cores` and `emulatorjs.auto_save_sync`. - `emulatorjs.disable_batch_bootup` was described as a DOS-specific `autorun.bat` knob. It now decides whether a multi-disc game hands the emulator every disc at once. - The exclusion defaults had drifted: `ini` is scanned again, the multi-file folder default now covers the frontend media folders, and the two `parts` lists share the single-file lists rather than carrying their own copies. - The gamelist and Pegasus exports merge into an existing file instead of overwriting it, and share one set of media folders. - Batocera, RetroBat and ES-DE folder names resolve without a `system.platforms` mapping. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- Exports merge into an existing file instead of overwriting it, share one set of media folders, keep a nested game's folder in its path, and now need `platforms.write` plus platform visibility. That last one breaks read-only tokens, so it is called out. - Firmware missing from disk is flagged rather than dropped, kept out of the player, 404s on its content endpoints, and cleared by the new Cleanup missing firmware task. - A Quick scan reconciles a known game's files with disk rather than skipping it outright, scans have their own queue and worker, and the scheduled-scan defaults on the page were two releases stale. - Title ids read out of ROM binaries, what they are used for, and the two `filesystem` keys that control them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- EmulatorJS remembers the core a game was launched with, operators can preselect one per platform, and a multi-disc game now boots every disc at once so discs swap from the emulator's own menu. - `emulatorjs.auto_save_sync` uploads a save whenever the emulator writes it, instead of only on save and quit. - Scheduling moved to RQ's own cron, the recommendations task is the one scheduled task that ships enabled, and the small-host advice was still telling people to set `SCAN_WORKERS=1` as though that were the default. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`DB_POOL_RECYCLE_SECONDS` retires a pooled connection before the server drops it for being idle, which is what the "server has gone away" errors on a quiet instance were. Glossary gains facet, jukebox, memory card, physical game, streaming session, title id, walkthrough and webstation. Four existing entries had gone stale: the full image now carries four runtimes rather than two, firmware and library both predate structure templates, and the watcher entry named `WATCHER_ENABLED`, which is not a variable RomM reads. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…acks The backend moved to Python 3.14 and the frontend to Node 24, neither of which the setup page stated at all. The Authentik and webstation stacks now live in their own compose files, so both are worth naming next to `docker compose up -d`. In-browser troubleshooting gains the threaded-core message, which used to surface as a generic error on a non-secure origin, and the slim-image entry now says which two runtimes have no CDN to fall back to. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- `scan.priority.region` now also decides which dump a group of siblings shows in the gallery, which the key's own section never said. - Company credits split into developers and publishers, which is what fills the `<developer>` and `<publisher>` export tags. - HowLongToBeat times back a gallery sort and filter, and a pinned match survives a rescan. - RomM sends PKCE on the OIDC authorization request, so an IdP that requires it needs nothing extra, and an OIDC username is sanitised before it is used. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The page listed seven filter fields against the roughly thirty the criteria dict actually carries, and flatly said there are no numeric thresholds, which the HowLongToBeat main-story range now contradicts. The fields are regrouped by shape (multi-value with its `_logic` companion, boolean, single-value) and taken from `collections_handler.py`, so the new `physical`, `has_soundtrack`, `publishers` and `developers` filters are in. Server Stats notes that a physical game counts as one entry at zero bytes, and that platform rows link through. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two more browser players, emulator streaming and Steam as a metadata source, none of which the introduction mentioned. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
rommapp/romm#4467 landed, so the five variables the two tables were generated against a branch for are now on master. Regenerating at this ref reproduces the committed snippets byte for byte. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The scope change is already in the release notes' API changes table, so the page doesn't need to carry it a second time. The See also pointer to API Authentication stays, since anyone calling these endpoints wants it whether or not the scope just moved. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A leading space inside the `[TITLEID][vVERSION]` code span (MD038), and the `<kbd>` tags in the PICO-8 controls table (MD033), which become plain code spans rather than adding another file-wide inline-HTML exemption. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The platform folder-alias work on main (#137) overlapped `system.platforms` in the config reference. Main's version documents the whole resolution order and links the generated alias table, which supersedes the one-line Batocera/RetroBat/ES-DE note this branch added, so the conflict is resolved in its favour. Scanning & Watcher's platform-folder section is repointed at that alias table for the same reason. Regenerating all four snippets at this branch's pin reproduces the merged files exactly, so the alias table needs no bump. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Both were prose and table rows inside sections about something else, so neither had an anchor the release notes could point at. Auto save sync moves out of "In-emulator behaviour" into its own section, with the config snippet and the reason it is off by default. Game length gets a section covering both the collection filter and the gallery sort, its dependency on HowLongToBeat, and the fact that unmatched games drop out of a length filter entirely. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The new pages all had the same tics. Almost every sentence trailed a
"so ..." or "since ..." clause explaining itself, claims came in
balanced pairs ("says a great deal and ... says almost nothing"), and
design rationale turned up where a reader just wants the fact. The
recommendations page managed to use "shelf" as a metaphor three times.
Shorter sentences, fewer subordinate clauses, and the reasoning kept
only where it changes what the reader does. Nothing factual changed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two real errors, both introduced by this branch: - The Windows 3.x/9x paragraph on the EmulatorJS page was inserted between two table rows, so the WonderSwan row rendered as literal pipes and the table ended early. - Smart Collections claimed every multi-value filter takes a `<field>_logic` companion. `platform_ids` is the one that doesn't. Two more claims that were wrong or would go wrong: - "The last four never contain a ROM binary" was positional and already miscounted, since `manual` is non-binary too and sits mid-table. The five are marked in the table now. - Folder Structure's trees predated `walkthrough`, `soundtrack` and `cheat`, so the page contradicted the table directly above them. The rest is duplication. Facts that live in a generated snippet or on a canonical page are stated there once and linked: the three hand-copied env-var tables, the `streaming` YAML example, the `scan.priority` defaults, the title-id platform list, the export merge semantics, and the filename tags. Also dropped a table column whose every cell read "Bundled", a Limitations list that restated the section above it, and a few paragraphs that only said there was nothing to do. `gen_scheduled_tasks.py` parsed `registry.py` twice, once per registry dict. It now parses once and shares the import map. Its silent `path not in paths` dedup is also gone: registry keys are unique, so two resolving to one module means `task_kwargs` would drop a task, which is what the rest of the function raises `UpstreamDrift` for. Output is byte-identical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Four paragraphs and a code block for one filter. Same facts in a single entry, and the `#game-length` anchor the release notes link to stays. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Cross-checked the new 5.3 pages against rommapp/romm at 839605e: - Recommended for you falls back to the library's best-reviewed games when there are no seeds or edges, so it is populated before the first index build; only similar games waits on it. - ENABLE_SCHEDULED_BUILD_RECOMMENDATIONS only gates the nightly task. It hides neither section, which users turn off in their own settings. - protocol and label are optional on a streaming container, a container-level emulator is ignored whenever platforms is used, and the play action is always named after the emulator. - memory_card_sync is ignored only on the platforms listed as cardless, not honoured solely on ps2 and ngc. - No startup warning is logged for a legacy container. - PICO-8 maps Z to the O button and X to the X button. - Non-binary file categories skip title-id extraction but are still hashed. Also unloosens the Play list on the using index, sorts the new glossary entries into their alphabetical slots, and fixes three typos. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Audit of the docs against the 5.3.0 release notes: new pages for the new features, updates to the pages the release changed, and a pass over the config, env var and setup references.
New pages
UPC_LOOKUP_*lookup, and what having no file excludes them fromwalkthrough/folder, the GameFAQs importer's plain-text-only contract, per-user reading progresssoundtrack/folders, its facets, generated mixes and playlists.p8/.p8.pngcarts on FAKE-08, with a PNG cart's own art used as its coverRewrites
streamingschema. Config is one entry per container with aplatformsmap, not one per emulator. Also covers container pools, the in-game save archive, the memory card library, live disc swap, joinable sessions, admin desktop sessions and the container fleet. The supported-platform table is rebuilt from the broker's capability tables, which now reach well past the original three emulators.Reference regeneration
sources.tomlis pinned at the 5.3 branch point and all three snippets are regenerated.gen_scheduled_tasks.pywas broken by rommapp/romm#4274: it read the task list out ofstartup.py's.init()calls andendpoints/tasks.py'smanual_tasks, both of which moved intobackend/tasks/registry.py. It now parses that registry and keeps its order.Five 5.3 variables shipped in
backend/config/__init__.pybut never reachedenv.template, which both generators treat as source of truth. Fixed upstream in rommapp/romm#4467 (merged), and this branch is pinned past it.Drift fixed along the way
Things the release notes didn't call out, found while checking the above against the source:
emulatorjs.disable_batch_bootupwas documented as a DOSautorun.batknob. It is now the multi-disc boot switch.iniis scanned again, and the multi-file default now covers the frontend media folders.scan.priority.artworkwas described as defaulting to the metadata order. It has carried its own for a while, led by the two artwork-only sources.WATCHER_ENABLED, which RomM does not read.SCHEDULED_RESCAN_CRON=0 0 * * *(really0 3 * * *) andSCAN_WORKERS=1.js-doshave a fallback, so Ruffle and PICO-8 do not work there at all.walkthroughandsoundtrack, which is where two of the new pages start.Not included
The
<!-- screenshot: ... -->placeholders in the release notes are unfilled. The new pages have no images.🤖 Generated with Claude Code