docs(v2): align v2 docs with actual implementation#937
Conversation
Audit of docs/v2 against src/ surfaced several config-breaking inaccuracies, missing components, and stale field lists. All claims verified directly against the config structs/enums (serde `tag = "type"`, no `rename_all`, so type tags must match variant names verbatim). Config-breaking fixes: - webhook: type "Webhook" -> "WebHook"; drop nonexistent error_policy - elasticsearch: type "Elastic" -> "ElasticSearch" - gcp_cloudfunction: authorization (string) -> authentication (bool) - pipeline_metrics: drop nonexistent `endpoint` field - stateful_cursor: Memory is the default; File default path is ./cursor.json; document max_breadcrumbs/flush_interval and Redis backend Newly documented components: - sinks: SqlDb, Zeromq - filters: IntoJson, WorkStats Backfilled fields: - kafka: ack_timeout_secs, paritioning - redis sink: correct default (oura-sink), add stream_max_length - terminal: adahandle_policy - finalize: max_block_quantity Data dictionary: - document the v2-native pipeline data model (ChainEvent envelope and Record variants) alongside the legacy v1 event catalogue Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 10 minutes and 7 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughDocumentation-only update for Oura v2: adds new pages for the ChangesOura v2 Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 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)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/v2/sinks/sql_db.mdx`:
- Line 41: The documentation incorrectly states that the `record` field is
omitted for `reset` events, but the actual behavior is that `record` is always
included in the data context and set to `null` for `reset` events. Update the
description of the `record` field to clarify that it is set to `null` for
`reset` events rather than being omitted, so template authors understand they
should check for null values rather than field existence when handling reset
events.
In `@docs/v2/sinks/zeromq.mdx`:
- Line 7: The documentation on line 7 states that the ZeroMQ sink "publishes
each event," which is too broad and doesn't match the actual implementation
behavior. The implementation skips reset events (events with no record). Revise
the sentence starting with "A sink that publishes each event" to clarify that
only events with records are published, and explicitly note that reset events
are not published over the socket.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 2c5eaa00-ec31-4f49-9db3-cb201408ce12
📒 Files selected for processing (14)
docs/v2/advanced/finalize_options.mdxdocs/v2/advanced/pipeline_metrics.mdxdocs/v2/advanced/stateful_cursor.mdxdocs/v2/filters/into_json.mdxdocs/v2/filters/work_stats.mdxdocs/v2/reference/data_dictionary.mdxdocs/v2/sinks/elasticsearch.mdxdocs/v2/sinks/gcp_cloudfunction.mdxdocs/v2/sinks/kafka.mdxdocs/v2/sinks/redis.mdxdocs/v2/sinks/sql_db.mdxdocs/v2/sinks/terminal.mdxdocs/v2/sinks/webhook.mdxdocs/v2/sinks/zeromq.mdx
The docker install reference only mentioned `latest` plus a single
pre-release versioned example. The Docker CI workflow
(.github/workflows/docker.yml) actually publishes: latest (main tip),
stable (newest release), v{major}, v{major}.{minor}, v{version}, and
sha-{commit}.
- add a table covering every published tag and when it updates
- clarify that `latest` tracks `main`, not the latest release
- use the v2.1.0 release (not a pre-release) as the pin example
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/v2/installation/docker.mdx`:
- Around line 37-47: The introductory sentence at the beginning of the Docker
tags table is misleading because it states that each build publishes several
tags, when in fact only the sha-{commit} tag is published on every build; the
other tags (latest, stable, and semver tags) are published conditionally based
on branch or release events. Reword the introduction to clarify that different
tags follow different publication triggers: latest tracks the main branch,
stable and semver tags are published only on releases, and sha-{commit} is the
only truly per-build tag. This will prevent users from incorrectly assuming all
listed tags are available after every build.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 653c5101-9068-4aea-8bd7-7f5ef0c2e601
📒 Files selected for processing (1)
docs/v2/installation/docker.mdx
…level [finalize] The top-level [finalize] block is not wired to the runtime (ConfigRoot.finalize / Context.finalize is deserialized but never consumed). The WorkStats filter is the only working finalization mechanism, so document it as such. Follow-up to remove the dead config tracked in #938. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
All three findings verified against the implementation: - sql_db: `record` is `null` on reset events (hbs_data renders the reset template with record=None -> null), not omitted. - zeromq: clarify that events without a record (resets) are skipped and not published (zeromq.rs returns early when record.is_none()). - docker: reword the tags intro; only `sha-*` is per-build, while `latest`/`stable`/semver tags are gated by branch/tag triggers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 participant
Context
An audit of
docs/v2/against the v2 implementation insrc/(and the CI workflows in.github/workflows/) surfaced several config-breaking inaccuracies, missing components, and stale references. A user copy-pasting some documented configs today would hit deserialization errors. Every claim in this PR was verified directly against the config structs/enums — the loader uses serdetag = "type"with norename_all, sotypetags must match the enum variant names verbatim.Config-breaking fixes (documented config would fail to load)
src/sinks/mod.rs):type = "Webhook"→"WebHook"; removed nonexistenterror_policyfield.type = "Elastic"→"ElasticSearch".src/sinks/gcp_cloudfunction.rs): documentedauthorization(string) replaced with the real fieldauthentication(bool).src/daemon/mod.rs): removed nonexistentendpointfield (MetricsConfigonly hasaddress; the path is fixed bygasket_prometheus).src/cursor/):Memoryis the default backend;Filedefault path is./cursor.json(notvar/oura/cursor); documentedmax_breadcrumbs/flush_intervaland added theRedisbackend.Newly documented components (implemented, previously undocumented)
SqlDb,ZeromqIntoJson,WorkStatsBackfilled stale field lists
ack_timeout_secs,paritioning(key intentionally matches the spelling in the code).oura-sink; addedstream_max_length.adahandle_policy.max_block_quantity.Docker installation reference (vs.
.github/workflows/docker.yml)The install doc only mentioned
latestplus a single pre-release versioned example, but the Docker workflow publishes many more tags.latest(main tip),stable(newest release),v{major},v{major}.{minor},v{version}, andsha-{commit}.latesttracks themainbranch rather than the latest release.v2.0.0-alpha.1) with thev2.1.0release.Data dictionary
Added a Pipeline Data Model section documenting the v2-native
ChainEventenvelope (apply/undo/reset+point) and theRecordvariants (CBOR block/tx, UTxORPC parsed block/tx, generic JSON, legacy v1) — previously only the legacy v1 catalogue was described.Notes
backoff_unit_sec/max_backoff_secvia serde) — no change needed.Noop/Assertsinks and theNoopfilter were intentionally left undocumented as internal/testing utilities.🤖 Generated with Claude Code
Summary by CodeRabbit
into_jsonandwork_statsfilters.finalizeoptions, metrics configuration requirements, and the stateful cursor (including backend-specific settings).authentication, Kafkaack_timeout_secsandparitioning, Redisstream_max_length, Terminal ADA Handle support, Webhook type naming, and the pipeline data model reference.