Update docs, site generator & verification

Add and reorder BIOS path entries in the site generator (BizHawk, EmuDeck, RetroPie, RomM). Update the add-platform pipeline steps and CI workflow notes. Document verification behavior changes: FirmwareDatabase index now includes sha256; RomM uses MD5 verification (verify.py checks MD5 only); BizHawk uses SHA1; severity label for GREEN adjusted to WARNING. Clarify troubleshooting/verify output semantics (UNTESTED and mismatch reporting), add profiling fields (core_classification option and adler32), fix several path and link typos (RetroDECK path, README/CONTRIBUTING links), and other small docs polishing.
2026-04-13 04:12:33 -05:00 · 2026-04-02 16:26:12 +02:00
parent 2f11542ed3
commit 92b270c054
9 changed files with 28 additions and 22 deletions
--- a/scripts/generate_site.py
+++ b/scripts/generate_site.py
@@ -331,10 +331,13 @@ def generate_home(
            "    |----------|-----------|",
            "    | RetroArch / Lakka | `system/` |",
            "    | Batocera | `/userdata/bios/` |",
+            "    | BizHawk | `Firmware/` |",
+            "    | EmuDeck | `Emulation/bios/` |",
            "    | Recalbox | `/recalbox/share/bios/` |",
            "    | RetroBat | `bios/` |",
            "    | RetroDECK | `~/retrodeck/bios/` |",
-            "    | EmuDeck | `Emulation/bios/` |",
+            "    | RetroPie | `~/RetroPie/BIOS/` |",
+            "    | RomM | `bios/{platform_slug}/` |",
            "",
        ]
    )
--- a/wiki/adding-a-platform.md
+++ b/wiki/adding-a-platform.md
@@ -324,10 +324,13 @@ python scripts/pipeline.py --offline
 This executes in sequence:

 1. `generate_db.py` - rebuild `database.json` from `bios/`
-2. `refresh_data_dirs.py` - update data directories
+2. `refresh_data_dirs.py` - update data directories (skipped with `--offline`)
 3. `verify.py --all` - verify all platforms including the new one
-4. `generate_pack.py --all` - build ZIP packs
+4. `generate_pack.py --all` - build ZIP packs + install manifests
 5. Consistency check - verify counts match between verify and pack
+6. Pack integrity - extract ZIPs and verify hashes per platform mode
+7. `generate_readme.py` - regenerate README
+8. `generate_site.py` - regenerate documentation site

 Check the output for:

--- a/wiki/architecture.md
+++ b/wiki/architecture.md
@@ -34,7 +34,7 @@ Upstream sources          Scrapers parse       generate_db.py scans
  batocera-systems                             builds database.json
  es_bios.xml (recalbox)                       (SHA1 primary key,
  core-info .info files                         indexes: by_md5, by_name,
-  FirmwareDatabase.cs                           by_crc32, by_path_suffix)
+  FirmwareDatabase.cs                           by_crc32, by_sha256, by_path_suffix)
  MAME/FBNeo source

 emulators/*.yml          verify.py checks      generate_pack.py resolves
@@ -254,7 +254,7 @@ python -m unittest tests.test_e2e -v

 | Workflow | File | Trigger | Role |
 |----------|------|---------|------|
-| Build & Release | `build.yml` | `workflow_dispatch` (manual) | restore large files, build packs, create GitHub release |
+| Build & Release | `build.yml` | push to main (bios/, platforms/) + manual | restore large files, build packs, create GitHub release |
 | Deploy Site | `deploy-site.yml` | push to main (platforms, emulators, wiki, scripts) + manual | generate site, build with MkDocs, deploy to GitHub Pages |
 | PR Validation | `validate.yml` | pull request on `bios/`/`platforms/` | validate BIOS hashes, schema check, run tests, auto-label PR |
 | Weekly Sync | `watch.yml` | cron (Monday 6 AM UTC) + manual | scrape upstream sources, detect changes, create update PR |
--- a/wiki/faq.md
+++ b/wiki/faq.md
@@ -89,7 +89,7 @@ A hash is a fixed-length fingerprint computed from a file's contents. If even on
 | SHA1 | 40 hex chars | `10155d8d6e6e832d8ea1571511e40dfb15fede05` |
 | CRC32 | 8 hex chars | `2F468B96` |

-Different platforms use different hash types for verification. Batocera uses MD5, RetroArch checks existence only, and RomM accepts any of the three.
+Different platforms use different hash types for verification. Batocera uses MD5, RetroArch checks existence only, BizHawk uses SHA1, and RomM uses MD5.

 ## Why does my verification report say UNTESTED?

--- a/wiki/getting-started.md
+++ b/wiki/getting-started.md
@@ -85,7 +85,7 @@ Relative to the RetroBat installation directory (e.g., `C:\RetroBat\bios\`).
 ### RetroDECK

 ```
-~/.var/app/net.retrodeck.retrodeck/retrodeck/bios/
+~/retrodeck/bios/
 ```

 ### EmuDeck
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -7,7 +7,7 @@ Technical documentation for the RetroBIOS toolchain.
 - **[Getting started](getting-started.md)** - installation, BIOS directory paths per platform, verification
 - **[FAQ](faq.md)** - common questions, troubleshooting, hash explanations

-If you just want to download BIOS packs, see the [home page](../index.md).
+If you just want to download BIOS packs, see the [home page](../README.md).

 ## Technical reference

@@ -26,7 +26,7 @@ If you just want to download BIOS packs, see the [home page](../index.md).
 - **[Testing guide](testing-guide.md)** - run tests, fixture pattern, how to add tests, CI integration
 - **[Release process](release-process.md)** - CI workflows, large files, manual release

-See [contributing](../contributing.md) for submission guidelines.
+See [contributing](../CONTRIBUTING.md) for submission guidelines.

 ## Glossary

--- a/wiki/profiling.md
+++ b/wiki/profiling.md
@@ -250,7 +250,7 @@ even if documentation mentions it.
 |-------|----------|-------------|
 | `emulator` | yes | display name |
 | `type` | yes | `libretro`, `standalone`, `standalone + libretro`, `alias`, `launcher`, `game`, `utility`, `test` |
-| `core_classification` | no | `pure_libretro`, `official_port`, `community_fork`, `frozen_snapshot`, `enhanced_fork`, `game_engine`, `embedded_hle`, `alias`, `launcher` |
+| `core_classification` | no | `pure_libretro`, `official_port`, `community_fork`, `frozen_snapshot`, `enhanced_fork`, `game_engine`, `embedded_hle`, `launcher`, `other` |
 | `source` | yes | libretro core repository URL |
 | `upstream` | no | original emulator repository URL |
 | `profiled_date` | yes | date of source analysis |
@@ -275,7 +275,7 @@ even if documentation mentions it.
 | `system` | system ID this file belongs to (for multi-system profiles) |
 | `size` | expected size in bytes |
 | `min_size`, `max_size` | size range when the code accepts a range |
-| `md5`, `sha1`, `crc32`, `sha256` | expected hashes from source code |
+| `md5`, `sha1`, `crc32`, `sha256`, `adler32` | expected hashes from source code |
 | `validation` | checks the code performs: `size`, `crc32`, `md5`, `sha1`, `adler32`, `signature`, `crypto`. Can be a list or dict `{core: [...], upstream: [...]}` for divergent checks |
 | `aliases` | alternate filenames for the same file |
 | `mode` | `libretro`, `standalone`, or `both` |
--- a/wiki/troubleshooting.md
+++ b/wiki/troubleshooting.md
@@ -72,13 +72,11 @@ filename from the emulator profile.

 ## Hash mismatch / UNTESTED

-`verify.py` reports `HASH_MISMATCH` or `UNTESTED` for a file.
-
-**HASH_MISMATCH:**
+`verify.py` reports `UNTESTED` for a file.

 The file exists and was hashed, but the computed hash doesn't match any expected
 value. This means you have a different version of the file than what the platform
-or emulator expects.
+or emulator expects. The reason field shows the expected vs actual hash prefix.

 To find the correct version, check the system page on the site. It lists every
 known BIOS file with its expected MD5 and SHA1.
@@ -147,10 +145,11 @@ How to read and interpret `verify.py` output.
 | Status | Meaning |
 |--------|---------|
 | `ok` | File present, hash matches (or existence check passed) |
-| `untested` | File present, hash not confirmed (existence-only platforms) |
+| `untested` | File present, hash not confirmed against expected value |
 | `missing` | File not found in the repository |
-| `hash_mismatch` | File found but hash doesn't match expected value |
-| `size_mismatch` | File found but size doesn't match what the emulator expects |
+
+Hash and size mismatches are reported as `untested` with a reason field
+showing expected vs actual values (e.g., `expected abc123… got def456…`).

 **Reading the output:**

--- a/wiki/verification-modes.md
+++ b/wiki/verification-modes.md
@@ -76,7 +76,7 @@ Recalbox uses three severity levels derived from two YAML fields (`mandatory` an
 |-----------|--------------------|--------|-------------------|
 | true      | true               | RED    | CRITICAL          |
 | true      | false              | YELLOW | WARNING           |
-| false     | (any)              | GREEN  | INFO              |
+| false     | (any)              | GREEN  | WARNING           |

 ### checkInsideZip (Batocera zippedFile)

@@ -93,9 +93,10 @@ If the inner file is not found inside the ZIP, the status is UNTESTED with a rea

 ### RomM verification

-RomM checks both file size and hash. It accepts any hash type (MD5, SHA1, or CRC32).
-ZIP files are not opened; only the container is checked. `verify.py` replicates this
-by checking size first, then trying each available hash.
+RomM uses MD5 verification (`verification_mode: md5`). The platform YAML stores
+SHA1, MD5, and CRC32 for reference, but `verify.py` checks only the MD5 field,
+matching the platform's runtime behavior. ZIP files are not opened; only the
+container is checked.


 ## SHA1 Mode