From d04939b813da2e9d5f4a0bc3e056616d78a57c90 Mon Sep 17 00:00:00 2001 From: Gaurav Patidar Date: Wed, 9 Sep 2026 13:23:59 +0530 Subject: [PATCH 1/3] fix:docs --- CONTRIBUTING.md | 19 +++++++++++++++++++ DATA_SOURCES.md | 30 ++++++++++++++++++++++++++++++ docs/KNOWN-ISSUES.md | 6 +++--- 3 files changed, 52 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6760dfdf1..029b53514 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,25 @@ through Pinokio; the terminal path above remains the contributor path. Open `http://localhost:4173`. Before sending a PR run `npm run build`, `npm test`, and `npm run test:track` (dev server must be up) — **all three must stay green.** +### Test prerequisites + +- **`npm test`** — unit tests. Runs standalone; no dev server or credentials + required. Exit code is the gate. +- **`npm run test:track`** — the 3D flight-tracking regression harness. It + drives the **real app** in headless Chromium, so it **requires a running + dev server** on the default port (`http://localhost:4173`). Pass + `--url ` to point it at another instance (e.g. + `node scripts/track-regression.mjs --url http://localhost:4272`). It does not + depend on live OpenSky / adsb.lol / AISStream (those are optional or + rate-limited locally); it installs a persistent `fetch` shim that returns + synthetic aircraft in the exact upstream payload shapes the layers parse. +- **`npm run build`** — production Vite build. No server or credentials + required; it validates that the client bundle compiles cleanly. + +If you change runtime behavior, update `docs/CURRENT-STATE.md` and +`CHANGELOG.md` in the same PR. For a deeper catalog of what each harness +checks and what it needs to run, see [TESTING.md](TESTING.md). + ## Good first contributions The highest-leverage places to jump in: diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md index faa351dca..bb0626117 100644 --- a/DATA_SOURCES.md +++ b/DATA_SOURCES.md @@ -125,6 +125,36 @@ the retrieval date (2026-07-30), exact download URL, license evidence, and the deterministic transform (`scripts/build-sf-neighborhoods.mjs`: `nhood` → `name`, ~2 m Douglas-Peucker simplification, 6-decimal rounding). +### Pilot CCTV source packs (`config/`) + +`config/cctv_sources.shinjuku.json` is a **demo source pack** (3 cameras: +Shinjuku Crossing, Shinjuku Station West, Shibuya Scramble) used for +projection-pipeline testing. The feeds are Google-hosted sample MP4 videos +(`storage.googleapis.com/gtv-videos-bucket/sample/`), not live public cameras. +Camera poses (coordinates, heading, pitch, FOV, mount height) are fabricated +priors placed at recognizable Tokyo intersections. + +Use the pack by setting: + +```bash +CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json npm run dev +``` + +Or equivalently, via `./scripts/dev-cctv.sh`: + +```bash +CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json ./scripts/dev-cctv.sh +``` + +The pack exercises the same CCTV registration and frustum-projection pipeline +as live city packs without requiring network access to a camera catalog. It is +**not** a live data source and carries no external attribution requirement. The +sample videos are publicly available Google test media. + +`config/cctv_sources.austin.json` is the reference live pack. Custom source +packs follow the same JSON schema (see either file); `CCTV_SOURCES_JSON` +accepts inline JSON as an alternative to a file path. + --- ## In-app attribution diff --git a/docs/KNOWN-ISSUES.md b/docs/KNOWN-ISSUES.md index 33c665f39..ca46d2ef0 100644 --- a/docs/KNOWN-ISSUES.md +++ b/docs/KNOWN-ISSUES.md @@ -57,9 +57,9 @@ Status: Open (owner-accepted 2026-07-08, documented) a few stragglers take one more poll. - **Born-grounded first poll:** a contact first seen on the ground with no altitude data renders at the geoid for ≤1 poll until its floor cell warms. -- Full context, improvement ideas, and the verification oracle - (`scripts/qa-floor-verify.mjs`): - `docs/superpowers/reports/2026-07-08-height-datum-handover.md`. +- Verify floor-placement behavior with `scripts/qa-floor-verify.mjs` against a + running local app; set `QA_BASE_URL` when it is not on the default port + (`http://localhost:4173`). --- From e3772f806f660ade51817707208250c7b7dd9a51 Mon Sep 17 00:00:00 2001 From: Gaurav Patidar Date: Fri, 11 Sep 2026 00:55:57 +0530 Subject: [PATCH 2/3] Clarify test:track command usage in CONTRIBUTING.md Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 029b53514..eef422a84 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,9 +33,8 @@ Open `http://localhost:4173`. Before sending a PR run `npm run build`, `npm test required. Exit code is the gate. - **`npm run test:track`** — the 3D flight-tracking regression harness. It drives the **real app** in headless Chromium, so it **requires a running - dev server** on the default port (`http://localhost:4173`). Pass - `--url ` to point it at another instance (e.g. - `node scripts/track-regression.mjs --url http://localhost:4272`). It does not + dev server** (default `http://localhost:4173`). To target another instance, + run `npm run test:track -- --url ` (or `node scripts/track-regression.mjs --url `). depend on live OpenSky / adsb.lol / AISStream (those are optional or rate-limited locally); it installs a persistent `fetch` shim that returns synthetic aircraft in the exact upstream payload shapes the layers parse. From c572a28e4484b45009d8ab71eb42e906109a7cff Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 2 Nov 2026 07:13:44 -0800 Subject: [PATCH 3/3] Mend the test prerequisites, document local CCTV packs without the dead demo feed, and credit the author --- CONTRIBUTING.md | 16 +++++----- DATA_SOURCES.md | 35 +++++---------------- changelog.d/210-contributor-docs-refresh.md | 4 +++ 3 files changed, 20 insertions(+), 35 deletions(-) create mode 100644 changelog.d/210-contributor-docs-refresh.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e625cd84..49c0b8ce3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,16 +34,18 @@ Open `http://localhost:4173`. Before sending a PR run `npm run build`, `npm test - **`npm run test:track`** — the 3D flight-tracking regression harness. It drives the **real app** in headless Chromium, so it **requires a running dev server** (default `http://localhost:4173`). To target another instance, - run `npm run test:track -- --url ` (or `node scripts/track-regression.mjs --url `). - depend on live OpenSky / adsb.lol / AISStream (those are optional or - rate-limited locally); it installs a persistent `fetch` shim that returns - synthetic aircraft in the exact upstream payload shapes the layers parse. + run `npm run test:track -- --url ` (or + `node scripts/track-regression.mjs --url `). It does not depend on + live OpenSky / adsb.lol / AISStream (those are optional or rate-limited + locally); it installs a persistent `fetch` shim that returns synthetic + aircraft in the exact upstream payload shapes the layers parse. - **`npm run build`** — production Vite build. No server or credentials required; it validates that the client bundle compiles cleanly. -If you change runtime behavior, update `docs/CURRENT-STATE.md` and -`CHANGELOG.md` in the same PR. For a deeper catalog of what each harness -checks and what it needs to run, see [TESTING.md](TESTING.md). +Each feature also has its own headless gate; see +[Feature regression gates](#feature-regression-gates) below. Docs and changelog +rules are under [Pull requests](#pull-requests). + ## Checking a built app locally Run `npm run build` followed by `npm run preview`. Preview serves the built diff --git a/DATA_SOURCES.md b/DATA_SOURCES.md index 0ae94b746..403972d5e 100644 --- a/DATA_SOURCES.md +++ b/DATA_SOURCES.md @@ -304,35 +304,14 @@ the retrieval date (2026-07-30), exact download URL, license evidence, and the deterministic transform (`scripts/build-sf-neighborhoods.mjs`: `nhood` → `name`, ~2 m Douglas-Peucker simplification, 6-decimal rounding). -### Pilot CCTV source packs (`config/`) +### Local CCTV source packs (`config/`) -`config/cctv_sources.shinjuku.json` is a **demo source pack** (3 cameras: -Shinjuku Crossing, Shinjuku Station West, Shibuya Scramble) used for -projection-pipeline testing. The feeds are Google-hosted sample MP4 videos -(`storage.googleapis.com/gtv-videos-bucket/sample/`), not live public cameras. -Camera poses (coordinates, heading, pitch, FOV, mount height) are fabricated -priors placed at recognizable Tokyo intersections. - -Use the pack by setting: - -```bash -CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json npm run dev -``` - -Or equivalently, via `./scripts/dev-cctv.sh`: - -```bash -CCTV_SOURCES_FILE=config/cctv_sources.shinjuku.json ./scripts/dev-cctv.sh -``` - -The pack exercises the same CCTV registration and frustum-projection pipeline -as live city packs without requiring network access to a camera catalog. It is -**not** a live data source and carries no external attribution requirement. The -sample videos are publicly available Google test media. - -`config/cctv_sources.austin.json` is the reference live pack. Custom source -packs follow the same JSON schema (see either file); `CCTV_SOURCES_JSON` -accepts inline JSON as an alternative to a file path. +The server can read a local camera list from `CCTV_SOURCES_FILE` (default +`config/cctv_sources.austin.json`, which ships empty) and inline JSON from +`CCTV_SOURCES_JSON`; the two are merged, and inline entries win on a duplicate +id. A non-empty local pack replaces the live open-data camera packs unless +`CCTV_FORCE_AUSTIN=1` is set. The packs under `config/` show the schema, and a +pack's cameras keep their own source's license and attribution. --- diff --git a/changelog.d/210-contributor-docs-refresh.md b/changelog.d/210-contributor-docs-refresh.md new file mode 100644 index 000000000..ed6dbe354 --- /dev/null +++ b/changelog.d/210-contributor-docs-refresh.md @@ -0,0 +1,4 @@ +- Contributor docs: CONTRIBUTING lists what each of the three baseline checks + needs to run, DATA_SOURCES documents loading a local CCTV source pack, and + KNOWN-ISSUES points the floor-placement note at its verification script + instead of a missing report (Gaurav Patidar, @gaurav7902, #210).