From 4b161ea7afcb6fb90a3ac3bdeb3af62bc2c4e5bc Mon Sep 17 00:00:00 2001 From: SurefireStudios <123013554+SurefireStudios@users.noreply.github.com> Date: Fri, 11 Sep 2026 12:15:39 -0700 Subject: [PATCH 1/2] docs: point contributors at the per-feature regression gates (#271) CONTRIBUTING.md named only npm run build, npm test and npm run test:track, so a contributor following it literally never learns that most features have a dedicated gate in scripts/qa-*.mjs. Today 25 of the 40 gates are not named in CURRENT-STATE.md either, so for those there was nothing in the written guide to find them by. Point at the directory rather than transcribing a list that would go stale the same way: every gate already opens with a comment saying what it asserts and how to run it, so `ls scripts/qa-*.mjs` plus the script header is the canonical, self-maintaining reference. Also state plainly that CI runs neither test:track nor any qa gate, since that is what makes running them locally matter. --- CONTRIBUTING.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a58227d8e..6a21f7251 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,6 +37,37 @@ configuration through the development app or environment file. Unknown API paths return JSON 404 responses. Vite preview is for checking a local build; it is not a production server. +## Feature regression gates + +Those three are the baseline, not the whole story. Most features also have a +dedicated headless gate under `scripts/qa-*.mjs` that drives the real app and +asserts that feature's contract. **Run the gate covering whatever you touched**, +and say which one you ran in the PR. + +The scripts are the canonical list, and each one documents itself: + +```bash +ls scripts/qa-*.mjs # every gate +head -20 scripts/qa-radio.mjs # what this gate proves, and how to run it +``` + +Every gate opens with a comment naming what it asserts. Most take +`--url http://localhost:` and need a dev server up; some need a specific +provider key or a particular port, and the header says which. Run them directly +with `node scripts/qa-.mjs`; only a couple (`qa:map-source-tray`, +`qa:transit`) have an `npm run` alias. + +If you aren't sure which gate covers your change, search `docs/CURRENT-STATE.md` +for the feature: it names the gate for many of them, and it's the authoritative +runtime reference either way. + +> **CI does not cover this for you.** The workflow runs the setup policy +> checks, the formatting and package-boundary checks, the unit suite and the +> production build, plus a Windows onboarding job. It runs neither +> `npm run test:track` nor any `qa-*.mjs` gate — both need a live dev server +> and a browser. For anything outside the unit suite, your local run +> is the only check before it reaches `main`. + ## Good first contributions The highest-leverage places to jump in: @@ -82,7 +113,7 @@ ownership and adoption process. ## Pull requests 1. Branch off `main`. -2. Keep `npm run build`, `npm test`, and `npm run test:track` green and avoid new console errors. +2. Keep `npm run build`, `npm test`, and `npm run test:track` green and avoid new console errors, plus the [feature gate](#feature-regression-gates) for the area you touched. 3. If you change runtime behavior, update `docs/CURRENT-STATE.md` and `CHANGELOG.md` in the same PR. 4. If you add or change a data source, update [DATA_SOURCES.md](DATA_SOURCES.md) with its license and attribution. **Don't add data you don't have the right to redistribute** — fetch it at runtime instead. 5. Describe what you changed and how you verified it (screenshots welcome for anything visual). From d01d10393c1a53a316edf7bd4b3d30469d4bab79 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Sun, 20 Sep 2026 19:35:56 -0700 Subject: [PATCH 2/2] docs: distinguish QA gates from helper modules --- CONTRIBUTING.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a21f7251..c65efac10 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,29 +44,31 @@ dedicated headless gate under `scripts/qa-*.mjs` that drives the real app and asserts that feature's contract. **Run the gate covering whatever you touched**, and say which one you ran in the PR. -The scripts are the canonical list, and each one documents itself: +Feature gates and a few supporting modules live under the same filename pattern: ```bash -ls scripts/qa-*.mjs # every gate -head -20 scripts/qa-radio.mjs # what this gate proves, and how to run it +ls scripts/qa-*.mjs # gates and their supporting modules +head -40 scripts/qa-radio.mjs # what this runnable gate proves and how to run it ``` -Every gate opens with a comment naming what it asserts. Most take -`--url http://localhost:` and need a dev server up; some need a specific -provider key or a particular port, and the header says which. Run them directly -with `node scripts/qa-.mjs`; only a couple (`qa:map-source-tray`, -`qa:transit`) have an `npm run` alias. +Runnable gate entrypoints document what they assert and how to invoke them. +Most need a dev server; some also need a specific provider key or port. Follow +the entrypoint's header rather than assuming every matching file accepts the +same arguments. Only a couple (`qa:map-source-tray`, `qa:transit`) have an +`npm run` alias. If you aren't sure which gate covers your change, search `docs/CURRENT-STATE.md` for the feature: it names the gate for many of them, and it's the authoritative -runtime reference either way. +runtime reference either way. `scripts/qa-l9-matrix.mjs` aggregates the broader +release-candidate checks and selected harnesses; it does not replace the focused +gate for the feature you changed. > **CI does not cover this for you.** The workflow runs the setup policy > checks, the formatting and package-boundary checks, the unit suite and the > production build, plus a Windows onboarding job. It runs neither > `npm run test:track` nor any `qa-*.mjs` gate — both need a live dev server -> and a browser. For anything outside the unit suite, your local run -> is the only check before it reaches `main`. +> and a browser. Include the applicable local run in your PR's validation +> evidence. ## Good first contributions