From bd50b08133ce314ce0bdcaa74f06075a2805bc10 Mon Sep 17 00:00:00 2001
From: Abdessamad Derraz <3028866+Abdess@users.noreply.github.com>
Date: Fri, 6 Nov 2026 14:49:06 +0100
Subject: [PATCH] docs: fetch platform files before the PR tests

---
 CONTRIBUTING.md            |  1 +
 scripts/generate_readme.py |  1 +
 tests/test_doc_surfaces.py | 25 +++++++++++++++++++++++++
 wiki/testing-guide.md      |  4 ++++
 4 files changed, 31 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 965d1a80a..3073b4eb2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -76,6 +76,7 @@ pip install pyyaml "jsonschema[format-nongpl]" markdown pyte hypothesis vermin s
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --added --strict  # each profile the branch adds
+python scripts/export_native.py --all --fetch --output-dir tmp/native  # files the exporter tests compare with
 python scripts/refresh_data_dirs.py  # data directories the pack-building tests read
 python scripts/generate_site.py       # the pages the site tests read
 npm ci --prefix website && npm run build --prefix website  # the built site, Node 24
diff --git a/scripts/generate_readme.py b/scripts/generate_readme.py
index 2dd324168..462b3d093 100644
--- a/scripts/generate_readme.py
+++ b/scripts/generate_readme.py
@@ -1002,6 +1002,7 @@ pip install pyyaml "jsonschema[format-nongpl]" markdown pyte hypothesis vermin s
 python scripts/validate_pr.py --changed          # the BIOS files the branch adds
 python scripts/validate_schemas.py --source-only # profiles and platform files
 python scripts/profile_sync.py --added --strict  # each profile the branch adds
+python scripts/export_native.py --all --fetch --output-dir tmp/native  # files the exporter tests compare with
 python scripts/refresh_data_dirs.py  # data directories the pack-building tests read
 python scripts/generate_site.py       # the pages the site tests read
 npm ci --prefix website && npm run build --prefix website  # the built site, Node 24
diff --git a/tests/test_doc_surfaces.py b/tests/test_doc_surfaces.py
index b7a53ee06..08a2702ba 100644
--- a/tests/test_doc_surfaces.py
+++ b/tests/test_doc_surfaces.py
@@ -611,3 +611,28 @@ class EveryOptionExists(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class ContributorChecksFetchThePlatformsFiles(unittest.TestCase):
+    """validate.yml fetches each platform's own file before the suite. The
+    checklist left it out, so the exporter fidelity cases skipped on a
+    contributor's clone and first ran, red, in CI."""
+
+    def test_the_pr_checklist_fetches_them_before_the_tests(self):
+        workflow = _read(".github/workflows/validate.yml")
+        self.assertLess(
+            workflow.index("python scripts/export_native.py --all --fetch"),
+            workflow.index("python -m unittest discover"),
+        )
+        for text in (
+            contributing_text(lambda page: page, "# C", "here"),
+            _read("CONTRIBUTING.md"),
+        ):
+            block = _section(text, "## Before opening a PR")
+            self.assertIn("python scripts/export_native.py --all --fetch", block)
+            self.assertLess(
+                block.index("export_native.py"), block.index("unittest discover")
+            )
+
+    def test_the_testing_guide_names_the_command(self):
+        self.assertIn("export_native.py --all --fetch", _read("wiki/testing-guide.md"))
diff --git a/wiki/testing-guide.md b/wiki/testing-guide.md
index 3345889d1..351ab614d 100644
--- a/wiki/testing-guide.md
+++ b/wiki/testing-guide.md
@@ -493,6 +493,10 @@ of main passes, not every commit under it.
 
 Modules that need real artifacts skip themselves when those artifacts are absent,
 so `test_pack_integrity` is a no-op in CI (no `dist/`) and a real check locally.
+The exporter fidelity cases go the other way: they compare with each platform's
+own file, which `python scripts/export_native.py --all --fetch --output-dir
+tmp/native` downloads into `.cache/upstream-native/`. CI runs it before the
+suite, and a clone without that cache skips them.
 Run `python -m unittest discover -s tests -t .` before pushing.
 
 Tests must pass before merge. If a test fails in CI, reproduce locally with: