docs: prep docs for publishing#187
Conversation
github-actions
Bot
added
documentation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request establishes the necessary infrastructure for publishing the project's documentation site. By modularizing the docs into a self-contained subproject and leveraging Cloudflare's native Git integration for deployments, the changes simplify maintenance and improve the developer experience. The refactored Makefile system ensures that the root build process remains clean and scalable as more subprojects are added. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughRoot docs build and deployment wiring is moved into a dedicated ChangesDocs subproject and policy rollout
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors the documentation site into its own self-contained Makefile subproject, moving its build, install, and preview logic out of the root Makefile. It also relocates the branding pipeline to the docs/ directory and configures automatic deployments to wavehouse.dev via Cloudflare Workers Builds. Feedback was provided on two items: a [SHOULD] recommendation to avoid setting compatibility_date to a future date in wrangler.jsonc to prevent unstable "time-travel" runtime behavior, and a [MAY] suggestion to invoke the build target recursively via $(MAKE) in the new docs/Makefile for better maintainability.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 2b47d380-ab3a-4dba-ab50-4449427abcbb
⛔ Files ignored due to path filters (3)
docs/scripts/branding/lockup.svgis excluded by!**/*.svgdocs/scripts/branding/mark.svgis excluded by!**/*.svgdocs/scripts/branding/og.template.svgis excluded by!**/*.svg
📒 Files selected for processing (9)
.github/actions/setup-env/action.ymlAGENTS.mdCHANGELOG.mdMakefiledocs/Makefiledocs/scripts/branding/generate.shdocs/scripts/screenshot.mjsdocs/src/content/docs/development.mddocs/wrangler.jsonc
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
docs/src/content/docs/development.md
📄 CodeRabbit inference engine (AGENTS.md)
Keep in sync with Makefile targets and build/test process changes
Files:
docs/src/content/docs/development.md
CHANGELOG.md
📄 CodeRabbit inference engine (AGENTS.md)
Document notable code changes under [Unreleased] section
Files:
CHANGELOG.md
Makefile
📄 CodeRabbit inference engine (AGENTS.md)
Update Makefile when adding new build targets or modifying build/test processes
Files:
Makefile
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Validate locally with make ci before pushing; do not use CI as your first feedback loop
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Merge (don't rebase) PR branches with main using git merge origin/main --no-edit; force-pushes are blocked
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Every review comment gets a substantive reply; resolve review threads before merge. Threads block merge via required_review_thread_resolution
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Agents (Claude Code, etc.) must create PRs with --draft and run pre-push-reviewer before pushing; only humans transition draft → ready-for-review
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Use the Repository pattern for data access (e.g., schema discovery, ingest pipeline, policy/pipes KV stores)
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Schema-driven ingest: POST /v1/ingest/{table} accepts flat JSON, validates against discovered ClickHouse schema, rejects unknown fields
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Async ingestion: ingest returns 200 after optional dedup + MQ publish; ClickHouse writes happen asynchronously via Bento pipeline
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Per-table batching: Bento ingest pipeline groups events by table name and performs dynamic INSERTs using schema's column order
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Dead Letter Queue (DLQ): Failed batch inserts publish to NATS stream WAVEHOUSE_DLQ with subjects dlq.<table> to prevent silent data loss
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Optional auth with JWKS: JWT authentication is opt-in via auth.enabled; supports HMAC shared secret and/or JWKS endpoint
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Optional dedup: Deduplication is opt-in via dedupe.enabled; dedupe.id_field config specifies which JSON field to use as dedup key
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Singleflight: TieredCache uses golang.org/x/sync/singleflight to prevent cache stampede
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Active Sweeper: NATS messages retained for SSE/WS gap-fill; Sweeper purges messages both ACKed and older than gap window
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Hasura-style access control: Per-table, per-role column-level and row-level permissions with JWT claim templating ({{ jwt.path }})
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Structured queries: POST /v1/tables/{table}/query with type-safe AST, permission enforcement, timestamp bucketing, and 10k-row limit cap
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Named query pipes: Pre-defined SQL templates with parameter binding, role restrictions, caching; stored in NATS KV with .sql file bootstrap
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Observability invariants: Stdout is always 100% (never sample); WARN+ERROR records always export at 100% regardless of logs.sample_rate
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Bearer-token-only CORS posture: Never emit Access-Control-Allow-Credentials; Bearer tokens are explicit request headers, not browser credentials
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Non-fatal boot: Schema-discovery failure on boot is non-fatal; server binds :8080 and retries discovery via RetryRefresh (exp backoff 2s → 60s)
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Interface-first design: Core behaviors are defined as Go interfaces (Cache, Deduplicator, Publisher, Subscriber); enables multiple implementations
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Bring Your Own Schema (BYOS): Users create tables directly in ClickHouse; WaveHouse discovers schemas by querying system.columns
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Every code change should update corresponding docs in the same PR; code without doc update is incomplete
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T16:19:36.927Z
Learning: Decision test for SDK updates: Would a wavehouse/sdk user's code need to change? If yes, SDK update needed. If no, no SDK update
🪛 checkmake (0.3.2)
docs/Makefile
[warning] 48-48: Target body for "help" exceeds allowed length of 5 lines (8).
(maxbodylength)
[warning] 84-84: Target body for "preview" exceeds allowed length of 5 lines (8).
(maxbodylength)
[warning] 129-129: Required target "all" is missing from the Makefile.
(minphony)
[warning] 129-129: Required target "test" is missing from the Makefile.
(minphony)
Makefile
[warning] 636-636: Target body for "tools" exceeds allowed length of 5 lines (7).
(maxbodylength)
[warning] 636-636: Required target "all" is missing from the Makefile.
(minphony)
🔇 Additional comments (4)
Makefile (1)
174-191: LGTM!Also applies to: 371-371, 384-423, 518-518, 636-636
docs/Makefile (1)
1-131: LGTM!docs/wrangler.jsonc (1)
5-12: LGTM!Also applies to: 15-33
docs/scripts/branding/generate.sh (1)
3-3: LGTM!Also applies to: 13-16, 25-28
github-project-automation
Bot
moved this from Backlog
to In review
in WaveHouse Task Board
There was a problem hiding this comment.
♻️ Duplicate comments (1)
CHANGELOG.md (1)
12-15:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winChangelog entry claims to close
#148but implementation differs from issue requirements.The issue
#148acceptance criteria explicitly required a.github/workflows/deploy-docs.ymlwithcloudflare/wrangler-actionand repository secrets. This entry describes Cloudflare dashboard-native Workers Builds instead. Either removeCloses#148`` from line 12 or update the issue's acceptance criteria to match the actual implementation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 22d9ce74-623b-4757-87d8-c00745e32885
📒 Files selected for processing (11)
.github/ISSUE_TEMPLATE/bug_report.md.github/ISSUE_TEMPLATE/config.yml.github/ISSUE_TEMPLATE/feature_request.mdAGENTS.mdCHANGELOG.mdCONTRIBUTING.mdREADME.mdSUPPORT.mddocs/src/components/Footer.astrodocs/src/config/sidebar.tsdocs/src/content/docs/index.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (2)
{CONTRIBUTING.md,.github/workflows/housekeeping.yml}
📄 CodeRabbit inference engine (AGENTS.md)
Keep
CONTRIBUTING.mdConventional Commits type list in sync with the regex inhousekeeping.ymlfor commit title linting
Files:
CONTRIBUTING.md
{SUPPORT.md,docs/src/components/Footer.astro,docs/src/config/sidebar.ts,README.md,.github/ISSUE_TEMPLATE/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
Update
SUPPORT.md, docs footer (docs/src/components/Footer.astro), docs sidebar (docs/src/config/sidebar.ts),README.md, and both issue templates when changing support policy
Files:
README.md.github/ISSUE_TEMPLATE/feature_request.mddocs/src/config/sidebar.ts.github/ISSUE_TEMPLATE/bug_report.mdSUPPORT.mddocs/src/components/Footer.astro
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Enforce 80% code coverage project-wide (merged unit + integration + e2e via `.testcoverage.yml`); per-suite minima: unit 70%, integration 12%, e2e 50%, SDK 50%
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Every new function should have corresponding test cases; validate with `make lint` and `make test` before considering work complete
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Update corresponding docs (`docs/src/content/docs/`) in the same PR as code changes; sync config struct tags, EventMessage JSON tags, route registrations, and error responses between code and documentation
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Validate locally before pushing with `make ci` (full parity with CI: parallel verify + builds + test-unit + test-sdk + subprojects, then integration + E2E + cov); enforce via pre-push git hook
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Use `make tools` to install pinned tools and git hooks (`.githooks/pre-commit` runs `make verify`; `.githooks/pre-push` checks for `tmp/ci-passed-<HEAD-sha>` marker)
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Enforce git merge (not rebase) for syncing PR branches with main to preserve inline review-thread anchors; long-lived branches must use `git merge origin/main --no-edit`
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Every review comment requires a substantive reply with commit SHA or reasoning; resolve all threads before merge (main branch protection enforces `required_review_thread_resolution`)
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Create AI agent PRs with `gh pr create --draft`; only humans transition draft → ready-for-review; re-trigger bot reviewers via PR comment mentions (claude for Claude, gemini-code-assist for Gemini)
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: AI agents must invoke `pre-push-reviewer` subagent in fresh context before pushing any branch with an open PR; subagent verdict must be `ship_it` (zero findings) before push is permitted
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Declare new area labels (e.g., `area/foo` for `internal/foo/`) in repo settings when adding new internal packages; `triage.yml` auto-discovers `area/*` labels at runtime via `gh label list` for issue routing
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Run `make verify` (tidy + fmt + vulncheck + lint) before every commit; use `make fix` to auto-apply corrections
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Run `make test-all` locally to execute unit + integration + E2E + SDK test suites; gates on coverage thresholds in `.testcoverage.yml`
Learnt from: CR
Repo: Wave-RF/WaveHouse
Timestamp: 2026-05-26T17:02:08.896Z
Learning: Use verbose test output with `V=1 make test` and custom run filters with `make test ARGS="-run TestFoo"` for targeted testing
🔇 Additional comments (11)
AGENTS.md (1)
421-421: LGTM!CHANGELOG.md (1)
28-31: LGTM!.github/ISSUE_TEMPLATE/config.yml (1)
3-8: LGTM!.github/ISSUE_TEMPLATE/bug_report.md (1)
44-46: LGTM!.github/ISSUE_TEMPLATE/feature_request.md (1)
26-28: LGTM!CONTRIBUTING.md (1)
5-6: LGTM!README.md (1)
163-169: LGTM!SUPPORT.md (1)
1-37: LGTM!docs/src/components/Footer.astro (1)
45-45: LGTM!Also applies to: 48-49
docs/src/config/sidebar.ts (1)
37-46: LGTM!docs/src/content/docs/index.mdx (1)
138-157: LGTM!
github-project-automation
Bot
moved this from In review
to In progress
in WaveHouse Task Board
github-project-automation
Bot
moved this from Ready
to In progress
in WaveHouse Task Board
github-project-automation
Bot
moved this from In progress
to Done
in WaveHouse Task Board
## Summary Continuation of #187 ## Plan - [ ] Footer is broken - [ ] Need to add lighthouse testing - [ ] Accessibility checks - [ ] AI accessibility checks - [x] Typos, spell checks, grammar, etc - [ ] Landing page cleanup & refactor content (maybe separate PR, tbd on scope/size) - [x] Metrics & Analytics (need to confirm being received in PostHog) - [ ] Live Demo? ## Related Issues - [x] Closes #148 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Summary
A large (hopefully final, apart from potentially a separate PR for content refactoring/touch-ups/restructuring) PR to lay the groundwork for all the docs/website stuff needed before going live.
Plan
pnpm workspace or something? Started in build(pnpm): migrate to pnpm 11 + add minimumReleaseAge + pin Node 22 #165 but need to finish as dependabot becomes simpler and pnpm/node versions with various subpackages in this monorepo allowing different versions in each becomes painful – this fixes that.(Unsure if we want yet or not, deferring until later/after alpha release)Related Issues: