refactor: write one contributing text for both pages

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 <name>`
 
-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/<name>.yml`
 5. Test: `python scripts/cross_reference.py --emulator <name>`
 
-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")

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 <name>`
-
-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/<name>.yml`
-5. Test: `python scripts/cross_reference.py --emulator <name>`
-
-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

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()