From 954e093271d847719987a48cfd01648d5cc85715 Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:30:37 +0200 Subject: [PATCH] docs: publish divergence table and license scope --- README.md | 9 +++++-- scripts/generate_readme.py | 11 +++++++- scripts/generate_site.py | 53 ++++++++++++++++++++++++++++++++++++-- 3 files changed, 68 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 68098bc6..3b5a5b60 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,9 @@ Full list with per-file details: **[https://abdess.github.io/retrobios/](https:/ | RetroPie | 530/530 (100.0%) | 530 | 0 | 0 | | RomM | 374/374 (100.0%) | 374 | 0 | 0 | +Coverage is measured against the file list each platform declares, using that platform's own verification mode. +Where platform lists and emulator source code disagree, the differences are tracked in the [gap analysis](https://abdess.github.io/retrobios/gaps/). + ## Build your own pack Clone the repo and generate packs for any platform, emulator, or system: @@ -146,6 +149,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -This repository provides BIOS files for personal backup and archival purposes. +The scripts and tooling are released under the [MIT License](LICENSE). +The BIOS and firmware files are not covered by that license: they are third-party system software, preserved and provided for personal backup, archival, and interoperability with emulation software. +The legal reasoning is laid out in the [FAQ](https://abdess.github.io/retrobios/wiki/faq/#is-this-legal). -*Auto-generated on 2026-08-07T12:31:35Z* +*Auto-generated on 2026-08-07T13:24:31Z* diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index 2744eace..7d498eab 100644 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -275,6 +275,11 @@ def generate_readme(db: dict, platforms_dir: str) -> str: lines.extend( [ + "", + "Coverage is measured against the file list each platform declares," + " using that platform's own verification mode.", + "Where platform lists and emulator source code disagree, the" + f" differences are tracked in the [gap analysis]({SITE_URL}gaps/).", "", "## Build your own pack", "", @@ -358,7 +363,11 @@ def generate_readme(db: dict, platforms_dir: str) -> str: "", "## License", "", - "This repository provides BIOS files for personal backup and archival purposes.", + "The scripts and tooling are released under the [MIT License](LICENSE).", + "The BIOS and firmware files are not covered by that license: they are" + " third-party system software, preserved and provided for personal" + " backup, archival, and interoperability with emulation software.", + f"The legal reasoning is laid out in the [FAQ]({SITE_URL}wiki/faq/#is-this-legal).", "", f"*Auto-generated on {ts}*", ] diff --git a/scripts/generate_site.py b/scripts/generate_site.py index aacd6cff..e9562c69 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -1435,6 +1435,7 @@ def generate_gap_analysis( coverages: dict, db: dict, data_names: set[str] | None = None, + registry: dict | None = None, ) -> str: """Generate a unified gap analysis page. @@ -1545,7 +1546,55 @@ def generate_gap_analysis( f"| {missing_str} " f"| {cov['mode']} |" ) - lines.append("") + lines.extend([ + "", + "Verification follows each platform's own runtime check " + "([how each mode works](wiki/verification-modes.md)): the counts " + "measure the repository against the file list each platform declares.", + "", + ]) + + # ---- Section 1b: platform lists vs emulator source ---- + + from truth import diff_platform_truth, generate_platform_truth + + div_rows = [] + for pname, cov in sorted(coverages.items(), key=lambda x: x[1]["platform"]): + truth_data = generate_platform_truth( + pname, cov["config"], (registry or {}).get(pname, {}), profiles, db + ) + s = diff_platform_truth(truth_data, cov["config"])["summary"] + div_rows.append( + f"| [{cov['platform']}](platforms/{pname}.md) " + f"| {s['total_missing']} " + f"| {s['total_extra_phantom'] + s['total_extra_unprofiled']} " + f"| {s['total_hash_mismatch']} " + f"| {s['total_required_mismatch']} |" + ) + + lines.extend([ + "## Platform Lists vs Emulator Source", + "", + "Platform file lists are scraped as-is from each upstream project. " + "Emulator profiles are read from source code. The two do not always " + "agree, and this table counts the differences. Packs follow the " + "platform contract; these numbers show where that contract diverges " + "from what the code loads.", + "", + "| Platform | Missing from list | Phantom | Hash conflict | Required status |", + "|----------|------------------:|--------:|--------------:|----------------:|", + *div_rows, + "", + "- **Missing from list**: a profiled emulator loads the file, the platform list does not mention it", + "- **Phantom**: on the platform list, loaded by no profiled emulator", + "- **Hash conflict**: the platform list and the emulator source expect different hashes", + "- **Required status**: required/optional differs between list and code", + "", + "The same comparison drives `scripts/exporter/`: each platform's " + "corrected list can be regenerated in its native format " + "(System.dat, es_bios.xml, batocera-systems.json, ...).", + "", + ]) # ---- Section 2: Problem files ---- @@ -2538,7 +2587,7 @@ def main(): print("Generating gap analysis page...") write_if_changed( str(docs / "gaps.md"), - generate_gap_analysis(profiles, coverages, db, suppl_names), + generate_gap_analysis(profiles, coverages, db, suppl_names, registry), ) # Wiki pages: copy manually maintained sources + generate dynamic ones