chore: merge site and docs fixes, fifth pass

This commit is contained in:
Abdessamad Derraz committed 2026-11-06 17:15:57 +01:00
commit b9f309940c
67 files changed
+1495 -786

No files matched your search

+8 -4
View File
@@ -19,7 +19,8 @@ boot, with no message saying why. It is not a guarantee either: source
profiles can document files nobody has dumped or that only the user can
provide, all of them visible in the [gap analysis](../gaps.md).
From a clone of the repository, `python scripts/generate_pack.py --platform
A clone carries the whole collection, several gigabytes, and `git clone
--depth 1` leaves its history out. From that clone, `python scripts/generate_pack.py --platform
retroarch --region us` builds a narrower pack, `--required-only` the bare
minimum each core needs to start, and `--no-game-data` keeps the firmware and
leaves out the files a game reads. `--help` lists every way to build your own,
@@ -134,9 +135,12 @@ Three rules keep a filtered pack usable:
- **No system is ever emptied.** If nothing matches, the whole group is kept.
`--region us` still ships `disksys.rom`, because the Famicom Disk System has no
American BIOS.
- **Region-free files always survive.** `psxonpsp660.bin`, `ps1_rom.bin` and
`openbios.bin` are declared `[world]`: they add a capability rather than
competing regionally.
- **Region-free files survive.** A file one of the platform's cores declares
`[world]` is kept. SwanStation declares `psxonpsp660.bin` and `ps1_rom.bin`
that way, DuckStation `openbios.bin`. The tag comes from each core:
PCSX ReARMed reads the region inside `psxonpsp660.bin` and files it as
`[japan]`, so on MinUI, NextUI and MyMinUI, where it is the only PlayStation
core, `--region us` drops it.
- **Untagged files always survive.** Most BIOS are not regional and carry no
`region:` at all.
+7 -2
View File
@@ -16,7 +16,8 @@ When a page opens, your browser sends one request to
carries:
- the page address, without the part after `?` or `#`;
- the site you came from, by its domain only (`google.com`, `reddit.com`).
- the site you came from, by its address without a path
(`https://www.google.com`).
GoatCounter reads the browser name and the country from that request. It does
not keep your IP address. To tell a reload from a second visitor it keeps a
@@ -25,9 +26,13 @@ code made from the request for 8 hours, then drops it.
These actions are counted the same way, with the page they happened on:
- a click on a copy button, a pack download or a file link;
- a click on a link to another site, by that site's domain (`reddit.com`);
- a site search that found nothing, so a missing page shows up. Its words are
sent only when they read as a file name (`scph5501.bin`, `scph5501`) or a
hash. Any other search is counted as "other", without its words;
hash with at least one letter. A word of letters with a few digits is sent
as typed, so a nickname written that way (`dupont1985`) would be too. A
number alone, such as a phone number, never is. Any other search is counted
as "other", without its words;
- the answer to "Did this page help?".
Not sent: your screen size, your language, a search that found results.
+22 -3
View File
@@ -42,7 +42,9 @@ tests are reported as skipped, so install them before a pull request
full-screen tests drive `install.py --tui` on a pseudo-terminal and read the
screen back with `pyte`, and fuzz the key decoder with `hypothesis`: both skip
without them (`pip install pyte hypothesis`). `pip install -e ".[dev]"` from the
checkout installs all of these at once, from the `dev` extra of `pyproject.toml`.
checkout installs all of these at once, from the `dev` extra of `pyproject.toml`,
which sets lower bounds only. The contributing guide's checklist reads the exact
versions CI pins from `validate.yml`.
No test framework beyond the standard library `unittest` module.
## Modules at a glance
@@ -377,6 +379,9 @@ to the way the project writes:
line naming a .info, core-info or System.dat no "is correct", "is
accurate", "still declares", "omits" or "missing". The note states what
that file declares and what the code reads.
- No pointer at a review in a comment, a docstring or a test name: a review
number in parentheses, a note file named after one, a test module or class
named after a review. The comment says what the code does.
Formatting stays: bold labels, lists, tables and admonitions make a page
easier to use. When markup shows raw on the site, the rendering is fixed and
@@ -460,8 +465,10 @@ A commit subject is English, 50 characters at most, `type: description` with a
lowercase word after the colon. The types are `feat`, `refactor`, `chore`,
`docs` and `fix`. The message does not use bug, regression, revert, dead code,
broken, wrong, hack, workaround or implement (derived forms included), nor the
marketing vocabulary above, and carries no Co-Authored-By trailer. A body
explains the why when the subject cannot: the scenario that failed, the
marketing vocabulary above, and carries no Co-Authored-By trailer. It says
what the change does, never which review asked for it: "review 3", "audit 12"
or "round 5" with its number points at notes no clone holds and is refused. A
body explains the why when the subject cannot: the scenario that failed, the
upstream `file:line` that decides it, what users will see.
```
@@ -469,6 +476,14 @@ feat: add retrobat platform support
refactor: extract shared utils to common.py
```
`scripts/commit_rules.py` holds these rules. Git does not copy hooks with a
clone, so the commit-msg hook that runs them is set up once per clone:
```bash
printf '#!/bin/sh\nexec python3 scripts/commit_rules.py "$1"\n' > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```
Files are staged by name, never with `git add -A` or `git add .`, which sweep in
deletions and work that is not yours. Generated artifacts (`database.json`,
`retired.json`, `derivable.json`, `install/*.json`, `README.md`, `CONTRIBUTING.md`, `exports/`,
@@ -512,6 +527,10 @@ of main passes, not every commit under it.
Modules that need real artifacts skip themselves when those artifacts are absent,
so `test_pack_integrity` is a no-op in CI (no `dist/`) and a real check locally.
The exporter fidelity cases go the other way: they compare with each platform's
own file, which `python scripts/export_native.py --all --fetch --output-dir
tmp/native` downloads into `.cache/upstream-native/`. CI runs it before the
suite, and a clone without that cache skips them.
Run `python -m unittest discover -s tests -t .` before pushing.
Tests must pass before merge. If a test fails in CI, reproduce locally with:
+5 -3
View File
@@ -817,8 +817,9 @@ hard-links `.cache/large/`, `data/` and the gitignored `bios/` files from the
main checkout. Before each job it is fast-forwarded, or rebased when it holds
unpushed commits, onto `origin/main`. A job that finds anything uncommitted
there stops as `blocked` and cleans nothing. Commits name their files
(`git commit -- <paths>`), and their subjects are checked against the
commit-msg hook when the registry loads. A job that leaves a change no commit
(`git commit -- <paths>`), and their subjects are checked against
`scripts/commit_rules.py`, the rules the commit-msg hook runs, when the
registry loads. A job that leaves a change no commit
rule takes fails.
`--push` sends the batch: rebase on `origin/main` (a conflict keeps the batch
@@ -1356,6 +1357,7 @@ before a release (wiki/release-process.md). Its lines stay in
| `slots.py` | Destinations the platform and a core both claim, and how the pack settles each (`--platform`, `--target`, `--json`, `--strict`, and pipeline step 3b passes the run's own `--target`) |
| `region_audit.py` | Confront every profile `region:` with the regions No-Intro names for the same dump (`--json`, `--db`, `--emulators-dir`). An opinion, never an authority: the code decides, and a disagreement is a line to read in the emulator's source |
| `validate_pr.py` | Validate BIOS files in pull requests, post markdown report |
| `pr_checks.py` | Run the checks `validate.yml` runs on a pull request, in its order, past a failure as CI does, and name each check that failed or whose tool is absent (`--list` prints them) |
| `validate_schemas.py` | Validate the data contracts: schemas and semantic invariants. `--source-only` checks `emulators/` and `platforms/` alone, which is what PR validation runs |
| `generate_event_schema.py` | Write `schemas/install-events.schema.json` from `EVENT_KEYS` in `install.py` (`--check` exits 1 when the file is stale, which `validate_schemas.py` also reports) |
| `generate_installer_doc.py` | Rewrite the generated blocks of `wiki/installer.md` from `install.py`: the tables (options, events, exit codes, keys per route, card markers), the line menu, and the run samples `install.py` prints in a sandbox against the committed `install/*.json`, so a new list rewrites the page (`--check` exits 1 when a block is stale, `--page FILE` writes another copy of the page). Pipeline step 7 |
@@ -1391,7 +1393,7 @@ Further options, by script:
| Script | Options |
|--------|---------|
| `auto_fetch.py` | `--create-issues` prints a GitHub issue body per file still missing. It posts nothing |
| `auto_fetch.py` | `--create-issues` prints a GitHub issue body per platform for the files still missing, with their full hashes. It posts nothing |
| `check_buildbot_system.py` | `--update` refreshes the entries found stale, `--json`, `--registry` |
| `check_freshness.py` | `--cache-dir`, `--native-cache-dir` (originals of the native export) and `--truth-dir` move the caches it reads |
| `check_release.py` | `--tag`, `--sums dist/SHA256SUMS.txt`, `--record` (default `release.json`), `--json` |