[claude] Move benchmarks-website planning docs into code comments#7810
Merged
connortsui20 merged 3 commits intodevelopfrom May 6, 2026
Merged
[claude] Move benchmarks-website planning docs into code comments#7810connortsui20 merged 3 commits intodevelopfrom
connortsui20 merged 3 commits intodevelopfrom
Conversation
Replace the nine-file `benchmarks-website/planning/` directory with project-level READMEs and module-level `//!` docs anchored to the code they describe. - New `benchmarks-website/README.md` is the v3 entry point: side-by-side with v2 explanation, architecture summary, route table, local-dev and deployment recipes, and the cutover plan. - New `benchmarks-website/AGENTS.md` carries just the still-load-bearing agent norms (don't touch v2, don't add a server-side classifier, the tooltip / slider / wheel-pan footguns). - `server/src/lib.rs` gains a crate-level module map + request-flow walkthrough (was: components/server.md). - `server/src/schema.rs` gains the full design-principles + per-table contract walkthrough (was: 01-schema.md). - `server/src/records.rs` and `server/src/ingest.rs` gain the wire envelope + HTTP-matrix docs (was: 02-contracts.md). - `vortex-bench/src/v3.rs` gains the producer mapping + per-binary inventory + per-suite query dim values table (was: benchmark-mapping.md and components/emitter.md). - The TODO breadcrumb on `api::charts::collect_group_charts` is rewritten to match the way the user already tracks the N+1 follow-up; the removed `planning/README.md` cross-reference goes away. - Decisions from `decisions.md` are folded into the relevant module doc where they still drive current behavior; everything else (alpha history, deferred phase-2 items) is dropped. Signed-off-by: Claude <noreply@anthropic.com>
…docs
Pre-cutover quality pass on `server/` and `migrate/`:
- `server/tests/common/mod.rs`: drop the 18 `unreachable_pub` warnings
per integration-test binary by switching every shared helper to
`pub(crate)`. The `#![allow(dead_code)]` stays — different test
binaries still use different subsets.
- `server/src/db.rs`: hoist the six function-scoped `use std::hash::Hasher`
statements to the module top, and add doc comments on `finish` and
`hasher_for` explaining why each exists.
- `server/src/{records, app, ingest}.rs` and `migrate/src/{classifier,
commits, v2, verify}.rs`: every previously-undocumented `pub` field
on the wire / state structs now carries a single-line `///` doc.
Field semantics (units, encoding, role) that were only implicit in
the field name are now explicit.
- `server/src/main.rs`: document the four environment variables
(`INGEST_BEARER_TOKEN`, `VORTEX_BENCH_DB`, `VORTEX_BENCH_BIND`,
`VORTEX_BENCH_LOG`) on the binary's `//!` doc.
- `server/src/{slug, error}.rs`: remove the last `planning/*.md`
cross-references, replacing them with the [`crate::*`] links that
point at the live source of truth.
- `static/chart-init.js`: fix the stale `server/src/html.rs` references
in two comment blocks (the file is now `server/src/html/mod.rs`),
rebuild the file map at the top to match the actual section
ordering, and add the two canvas state contract entries
(`__bench_display_unit`, `__bench_y_user_set`) that the orientation
comment had drifted from.
Verification:
- `cargo clippy -p vortex-bench-server -p vortex-bench-migrate --all-targets
--all-features -- -W dead_code -W unreachable_pub -W unused_imports`
→ 0 warnings.
- `cargo test -p vortex-bench-server -p vortex-bench-migrate` → all 140+
tests pass.
- `cargo test --doc -p vortex-bench-server -p vortex-bench-migrate` → 0
failures.
- No snapshot regenerated.
- v2 site files (`server.js`, `src/`, `package.json`, etc.) untouched.
Signed-off-by: Claude <noreply@anthropic.com>
connortsui20
changed the title
…gration Doc-accuracy nits surfaced in review of #7810. No behavior changes. - `vortex-bench/src/datasets/mod.rs::Dataset::v3_dataset_dims`: drop the stale "Public-BI emits dataset = public-bi, dataset_variant = …" example. The only override (`PBIBenchmark::v3_dataset_dims`) actually returns `(&self.name, None)` to match the migrate classifier — the parent-namespace framing was historical. Reword to "Override only when a suite needs a different dataset name on the wire than its `name()` returns." - `query_idx` field doc on both `vortex-bench/src/v3.rs` and `server/src/records.rs`: drop the "1-based" claim. Query indices are whatever the producing bench loop happens to use (ClickBench is 0-based, others vary); both sides agree only because the migrate classifier parses literal digits out of `q07`-style v2 chart names. - `server/src/app.rs`: add `/api/group/{slug}` to the read-API line; the router wires it but the module doc had drifted. - `server/src/api/charts.rs::collect_group_charts`: re-introduce a `TODO(#7812):` marker so the N+1 follow-up is grep-discoverable. Tracking issue: #7812 - `benchmarks-website/README.md`: rewrite the cutover-plan bullet to reflect that v3 runs alongside v2 on the same EC2 host (v2 on `:80`, v3 on `:3001`), per `docker-compose.yml` and `ec2-init.txt`. The earlier "separate EC2 host" claim was stale. - `server/src/ingest.rs`: add the missing 400 row for the older-than- expected `schema_version` case to the HTTP matrix table. - `vortex-bench/src/v3.rs`: drop the `[`canonical_tpc_scale_factor`]` intra-doc link in the new dim-mapping table — the function is private, so `RUSTDOCFLAGS="-D warnings" cargo doc` rejected it. - `server/src/lib.rs`: rename "PNGs" to "logos" in the route table — typos parsed "PN" inside "PNGs" as a typo of "ON" and failed `Spell Check with Typos`. Verification: - `cargo +nightly fmt --all` - `cargo build -p vortex-bench-server -p vortex-bench-migrate` → clean. - `cargo test -p vortex-bench-server -p vortex-bench-migrate` → all 140+ tests pass. - `cargo clippy --all-targets --all-features -p vortex-bench-server -p vortex-bench-migrate -- -W dead_code -W unreachable_pub -W unused_imports` → 0 warnings. - `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p vortex-bench -p vortex-bench-server -p vortex-bench-migrate` → clean. - `typos .` → 0 hits. Signed-off-by: Claude <noreply@anthropic.com>
joseph-isaacs
approved these changes
May 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR consolidates the benchmarks-website v3 planning documentation from the
planning/directory into inline code comments and a top-levelREADME.md, making the architecture and wire contracts discoverable alongside the implementation.Changes:
planning/directory (00-overview.md, 01-schema.md, 02-contracts.md, AGENTS.md, README.md, decisions.md, deferred.md, benchmark-mapping.md, components/*.md)benchmarks-website/README.mdwith v2/v3 architecture overview and deployment notesbenchmarks-website/AGENTS.mdwith contributor guidelines for the v3 codebase01-schema.mdintoserver/src/schema.rsdoc comments02-contracts.mdintoserver/src/records.rsandvortex-bench/src/v3.rsdoc commentsserver/src/ingest.rsdoc commentsserver/src/lib.rs,server/src/db.rs,server/src/slug.rs,server/src/error.rs,server/src/app.rs,server/src/api/mod.rs,server/src/api/dto.rs,migrate/src/v2.rs,migrate/src/classifier.rs,migrate/src/commits.rs,migrate/src/verify.rs, andvortex-bench/src/datasets/mod.rsto reference the new doc locations and clarify their rolesserver/tests/common/mod.rs(pub → pub(crate))The planning docs were comprehensive but lived outside the codebase, making them easy to miss during development and harder to keep in sync with implementation. This change embeds the essential contracts and design rationale where developers will encounter them: in the module docs and type definitions they're working with.
Testing
Existing tests pass. No functional changes to the server, migrator, or emitter — only documentation reorganization and visibility adjustments.
https://claude.ai/code/session_012kmSMpZiKfQcHw3PedaFR4