From 313637663ac06394bf8a268afdd15ca1600fb455 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Wed, 25 Mar 2026 14:51:57 +0100 Subject: [PATCH] docs: soften tone, explain methodology without dismissing other sources --- README.md | 20 +++++++++++--------- scripts/generate_readme.py | 18 ++++++++++-------- scripts/generate_site.py | 16 +++++++++------- 3 files changed, 30 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 57e8d15e..7af5cd63 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,21 @@ Source-verified BIOS and firmware packs for retrogaming platforms. -Every file in this collection is traced to its ground truth: the emulator's source code. -Not .info files, not documentation, not community wikis - the actual code that loads the file. -305 emulators profiled from source, 8 platforms cross-referenced, +Documentation and metadata can drift from what emulators actually load at runtime. +To keep packs accurate, each file here is checked against the emulator's source code: +what the code opens, what hashes it expects, what happens when a file is missing. +305 emulators profiled, 8 platforms cross-referenced, 6,733 files verified. ### How it works -1. **Profile emulators from source code** - read the code, document every file loaded, its hash, size, and validation -2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs -3. **Build packs** - for each platform, include the baseline files + what its cores actually require -4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size) +1. **Read emulator source code** - identify every file the code loads, its expected hash and size +2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare +3. **Build packs** - for each platform, include its baseline files plus what its cores need +4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, size) -When a platform and an emulator disagree on a file, we detect it. When a better variant exists in the repo, we use it. +When a platform and an emulator disagree on a file, the discrepancy is reported. +When a variant in the repo satisfies both, it is preferred automatically. > **6,733** files | **5043.6 MB** | **8** platforms | **305** emulator profiles @@ -61,4 +63,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. This repository provides BIOS files for personal backup and archival purposes. -*Auto-generated on 2026-03-25T13:49:31Z* +*Auto-generated on 2026-03-25T13:51:15Z* diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index bbabcd41..fa66ad29 100644 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -101,19 +101,21 @@ def generate_readme(db: dict, platforms_dir: str) -> str: "", "Source-verified BIOS and firmware packs for retrogaming platforms.", "", - "Every file in this collection is traced to its ground truth: the emulator's source code.", - "Not .info files, not documentation, not community wikis - the actual code that loads the file.", - f"{emulator_count} emulators profiled from source, {len(coverages)} platforms cross-referenced,", + "Documentation and metadata can drift from what emulators actually load at runtime.", + "To keep packs accurate, each file here is checked against the emulator's source code:", + "what the code opens, what hashes it expects, what happens when a file is missing.", + f"{emulator_count} emulators profiled, {len(coverages)} platforms cross-referenced,", f"{total_files:,} files verified.", "", "### How it works", "", - "1. **Profile emulators from source code** - read the code, document every file loaded, its hash, size, and validation", - "2. **Cross-reference with platforms** - each platform (RetroArch, Batocera, Recalbox...) declares what it needs", - "3. **Build packs** - for each platform, include the baseline files + what its cores actually require", - "4. **Verify everything** - platform-native verification (MD5, existence) + emulator-level validation (CRC32, SHA256, size)", + "1. **Read emulator source code** - identify every file the code loads, its expected hash and size", + "2. **Cross-reference with platforms** - match against what RetroArch, Batocera, Recalbox and others declare", + "3. **Build packs** - for each platform, include its baseline files plus what its cores need", + "4. **Verify** - run each platform's native checks (MD5, existence) and emulator-level validation (CRC32, size)", "", - "When a platform and an emulator disagree on a file, we detect it. When a better variant exists in the repo, we use it.", + "When a platform and an emulator disagree on a file, the discrepancy is reported.", + "When a variant in the repo satisfies both, it is preferred automatically.", "", f"> **{total_files:,}** files | **{size_mb:.1f} MB** | **{len(coverages)}** platforms | **{emulator_count}** emulator profiles", "", diff --git a/scripts/generate_site.py b/scripts/generate_site.py index 19580c39..7ba4b55a 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -221,17 +221,19 @@ def generate_home(db: dict, coverages: dict, profiles: dict, "", "## Methodology", "", - "Every file in this collection is traced to its **ground truth**: the emulator's source code.", + "Documentation and metadata can drift from what emulators actually load at runtime.", + "To keep packs accurate, each file here is checked against the emulator's source code.", "", - "Three levels of truth, in order of authority:", + "The source code is the primary reference because it reflects actual behavior.", + "Other sources remain useful but are verified against it:", "", - "1. **Upstream emulator source** - the original project (Dolphin, PCSX2, Mednafen...)", - "2. **Libretro core source** - the RetroArch port, which may diverge (different paths, added/removed files)", - "3. **`.info` declarations** - metadata files that can be wrong or outdated", + "1. **Upstream emulator source** - what the original project loads (Dolphin, PCSX2, Mednafen...)", + "2. **Libretro core source** - the RetroArch port, which may adapt paths or add files", + "3. **`.info` declarations** - metadata that platforms rely on, checked for accuracy", "", - f"**{emulator_count}** emulators profiled from source code. " + f"**{emulator_count}** emulators profiled. " f"Each profile documents what the code loads, what it validates, " - f"and where the upstream diverges from the port.", + f"and where the port differs from the original.", "", f"**{total_files:,}** files | **{len(coverages)}** platforms | " f"**{emulator_count}** emulator profiles | **{_fmt_size(total_size)}** total",