From 72e47becb4617f948b3889aad1abd1fd63daf82c Mon Sep 17 00:00:00 2001 From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com> Date: Tue, 6 Oct 2026 09:47:09 +0200 Subject: [PATCH] refactor: write one contributing text for both pages --- scripts/generate_readme.py | 26 ++++++++++---- scripts/generate_site.py | 61 +++------------------------------ tests/test_contributing_text.py | 35 +++++++++++++++++++ 3 files changed, 59 insertions(+), 63 deletions(-) create mode 100644 tests/test_contributing_text.py diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py index 4cf67189..2cf5d127 100644 --- a/scripts/generate_readme.py +++ b/scripts/generate_readme.py @@ -641,8 +641,14 @@ def generate_readme(db: dict, platforms_dir: str) -> str: return "\n".join(lines) + "\n" -def generate_contributing() -> str: - return f"""# Contributing to RetroBIOS +def contributing_text(link, title: str, site_words: str) -> str: + """The contribution guide, one text for the repository and the site. + + Two copies drifted apart: four steps to add a platform here, five on the + site. *link* renders a site page (absolute URL for the README, relative + .md for MkDocs); *site_words* names the site from where the text is read. + """ + return f"""{title} ## Add a BIOS file @@ -651,7 +657,7 @@ def generate_contributing() -> str: 3. Variants (alternate hashes for the same file): `bios/Manufacturer/Console/.variants/` 4. Open a Pull Request - hashes are verified automatically and reported as a comment -The [dump provenance]({SITE_URL}provenance/) page lists catalogued dumps still +The [dump provenance]({link("provenance")}) page lists catalogued dumps still missing from the collection, with their hashes. A file matching one of those is the most useful contribution. @@ -662,7 +668,7 @@ the most useful contribution. 3. Register it in `platforms/_registry.yml` 4. Generate the platform YAML and test: `python scripts/verify.py --platform ` -Full walkthrough: [adding a platform]({SITE_URL}wiki/adding-a-platform/). +Full walkthrough: [adding a platform]({link("wiki/adding-a-platform")}). ## Add an emulator profile @@ -672,7 +678,7 @@ Full walkthrough: [adding a platform]({SITE_URL}wiki/adding-a-platform/). 4. Write the YAML to `emulators/.yml` 5. Test: `python scripts/cross_reference.py --emulator ` -Full walkthrough: [profiling guide]({SITE_URL}wiki/profiling/). +Full walkthrough: [profiling guide]({link("wiki/profiling")}). ## File conventions @@ -697,10 +703,18 @@ configs, validates the YAML against the schemas, runs the test suite, and posts a report on the PR. Contributors who add platform support are credited in the README, -on the documentation site, and in the BIOS packs. +{site_words}, and in the BIOS packs. """ +def generate_contributing() -> str: + return contributing_text( + lambda page: f"{SITE_URL}{page}/", + "# Contributing to RetroBIOS", + "on the documentation site", + ) + + def main(): parser = argparse.ArgumentParser(description="Generate slim README.md") parser.add_argument("--db", default="database.json") diff --git a/scripts/generate_site.py b/scripts/generate_site.py index af7fa1f3..0daf4f5e 100644 --- a/scripts/generate_site.py +++ b/scripts/generate_site.py @@ -3108,64 +3108,11 @@ def generate_cross_reference( def generate_contributing() -> str: - return """# Contributing - RetroBIOS + from generate_readme import contributing_text -## Add a BIOS file - -1. Fork this repository -2. Place the file in `bios/Manufacturer/Console/filename` -3. Variants (alternate hashes for the same file): place in `bios/Manufacturer/Console/.variants/` -4. Open a Pull Request - hashes are verified automatically and reported as a comment - -The [dump provenance](provenance.md) 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 - -1. Create a scraper in `scripts/scraper/` (inherit `BaseScraper`) -2. Read the platform's upstream source to determine how it checks BIOS files -3. Add an entry to `platforms/_registry.yml` -4. Generate the platform YAML config -5. Test: `python scripts/verify.py --platform ` - -Full walkthrough: [adding a platform](wiki/adding-a-platform.md). - -## Add an emulator profile - -1. Clone the emulator's source code, upstream and libretro port -2. Trace the file loading from the entry point, not from a keyword grep -3. Document every file the code loads, with a `source_ref` line reference -4. Write the YAML to `emulators/.yml` -5. Test: `python scripts/cross_reference.py --emulator ` - -Full walkthrough: [profiling guide](wiki/profiling.md). - -## File conventions - -- `bios/Manufacturer/Console/filename` for canonical files -- `bios/Manufacturer/Console/.variants/filename.sha1prefix` for alternate versions -- Files >50 MB go in GitHub release assets (`large-files` release) -- RPG Maker and ScummVM directories are excluded from deduplication -- Two paths differing only by case break clones on Windows and macOS; - `tests/test_no_case_collisions.py` enforces this - -## Before opening a PR - -```bash -python -m unittest discover tests -python scripts/pipeline.py --offline -``` - -## PR validation - -CI computes SHA1/MD5/CRC32 for every new file, checks them against the platform -configs, validates the YAML against the schemas, runs the test suite, and posts -a report on the PR. - -Contributors who add platform support are credited in the README, on this site, -and in the BIOS packs. -""" + return contributing_text( + lambda page: f"{page}.md", "# Contributing - RetroBIOS", "on this site" + ) # Wiki pages diff --git a/tests/test_contributing_text.py b/tests/test_contributing_text.py new file mode 100644 index 00000000..c64846d5 --- /dev/null +++ b/tests/test_contributing_text.py @@ -0,0 +1,35 @@ +"""CONTRIBUTING.md and the site's contributing page say the same thing. + +Two generators wrote the page and drifted: four steps to add a platform in +the repository, five on the site, under two different titles. +""" + +from __future__ import annotations + +import re +import sys +import unittest +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(REPO_ROOT / "scripts")) + +import generate_readme # noqa: E402 +import generate_site # noqa: E402 + + +def _normalized(text: str) -> str: + text = re.sub(r"\]\([^)]*\)", "](link)", text) + return "\n".join(text.splitlines()[1:]).replace("on this site", "on the documentation site") + + +class OneContributingText(unittest.TestCase): + def test_repository_and_site_pages_match(self): + self.assertEqual( + _normalized(generate_readme.generate_contributing()), + _normalized(generate_site.generate_contributing()), + ) + + +if __name__ == "__main__": + unittest.main()