Abdessamad Derraz
123d698e43
generate_site.py writes the Starlight project in website/ and nothing else: mkdocs.yml, the MkDocs hooks, theme overrides and stylesheet go, and the wiki is written in Starlight's syntax. Both workflows set up Node with the official actions/setup-node pinned by commit, run npm ci from the committed lockfile, build with the strict link validator and check the result with validate_site.py. The search weighs a page by what it answers: Start here pages first, a system page's cards and file names before a guide citing them, deep guides, launchers, aliases and frozen copies after. Status badges, hash blocks and the export change lists leave the index. The ranking sits at the centre of a range where the 13 queries of search_gate.py all answer, in the search box itself. 839 pages, every URL and 45,611 ids match the MkDocs build. The tests read the Starlight content and syntax.
3.8 KiB
Contributing to RetroBIOS
Add a BIOS file
One file needs no clone and no local setup:
- Upload it into
bios/from the browser, 25 MB at most per file. GitHub writes it to a fork and opens the pull request. - CI hashes it and looks it up in every platform list and emulator profile. For a file it recognises, it names the folder holding the other files of its system. The report is in the summary of the pull request's Validation run.
- The file can be moved to that folder in the same pull request. A file whose
hash differs from the one already held under its name goes to that folder's
.variants/.
From a clone, the file goes to bios/Manufacturer/Console/filename, and
python scripts/validate_pr.py path/to/file names that folder for a file still
outside bios/. A file over the browser's 25 MB limit goes in that way.
The dump provenance page lists catalogued dumps still missing from the collection, with their hashes. A file matching one of those is the most useful contribution.
Add a platform
- Write a scraper in
scripts/scraper/(inheritBaseScraper) - Read the platform's upstream source to determine how it checks BIOS files
- Register it in
platforms/_registry.yml - Generate the platform YAML and test:
python scripts/verify.py --platform <name>
Full walkthrough: adding a platform.
Add an emulator profile
- Clone the emulator's source code, upstream and libretro port
- Trace the file loading from the entry point, not from a keyword grep
- Document every file the code loads, with a
source_refline reference - Write the YAML to
emulators/<name>.yml - Test:
python scripts/cross_reference.py --emulator <name>
Full walkthrough: profiling guide.
File conventions
bios/Manufacturer/Console/filenamefor canonical filesbios/Manufacturer/Console/.variants/filename.sha1prefixfor alternate versions- A file too large for git goes to the
large-filesGitHub release and its path into.gitignore, the list that decides what is served from the release - Trees addressed by path are kept out of deduplication (
NODEDUP_DIRSinscripts/dedup.py) - Two paths differing only by case break clones on Windows and macOS,
and
tests/test_no_case_collisions.pyenforces this
Before opening a PR
A pull request that only adds files under bios/ needs none of this: the
validation above is its check. For code, profiles or platform files, these are
the checks CI runs on a pull request (Python 3.12 or newer):
pip install pyyaml "jsonschema[format-nongpl]" markdown
python scripts/validate_pr.py --changed # the BIOS files the branch adds
python scripts/validate_schemas.py --source-only # profiles and platform files
python scripts/profile_sync.py --changed --strict # each profile the branch adds or edits
python scripts/refresh_data_dirs.py # data directories the pack-building tests read
python -m unittest discover -s tests -t .
The full pipeline is not needed for a contribution: it rebuilds every pack
in dist/, which is why maintainers run it before a release.
PR validation
CI computes SHA1/MD5/CRC32 for every new file, checks them against the platform configs, validates the YAML against the schemas, confronts each added profile with its upstream source and runs the test suite. The BIOS report goes to the summary of the Validation run, and also to a comment when the branch lives in this repository: a fork's pull request runs with a read-only token.
Contributors who add platform support are credited in the README, on the documentation site, and in the BIOS packs.