docs(exercises): rewrite 00-baseline in house style, quality-pass 01-06 - #183
Merged
Conversation
Bring the exercises to one consistent, reality-first standard. - 00-baseline: replace the 1192-line app-dev tutorial (Level 1-4 tiers, ToC, evaluation criteria) with a ~200-line Phase-0 operability exercise matching 01-06: tour the whitebox layer that ships at baseline (D6 endpoints, the SLO recording rules, the provisioned dashboard), then add a `description` field and *operate* it end to end. The hand-built ItemOut is the load-bearing trap: a green build, applied migration, and persisted column can still hide an API that never returns the field -- "done means operable", not 200. - 01-06: correctness pass (every command, path, metric, alert window, panel title, port, and make target verified against the current tree; fixed a GC panel name and an unpinned Load panel), one shared section structure and command style across all six, and prose/step/discussion polish -- preserving each hard-won specific (the anomaly-aliasing formula, the GC sawtooth and D10 degradation, the event-stream break, the incident-to-inbox flow).
|
Warning Review limit reached
Next review available in: 54 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
WalkthroughThe PR rewrites Phase 0–6 exercise documentation with current platform checks, monitoring signals, failure timing, event-stream recovery, alert notification behaviour, anomaly visibility calculations, and GC degradation verification. ChangesDevOps exercise curriculum
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ 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: 7
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/exercises/03-break-the-event-stream.md (1)
156-171: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winDo not describe all four signals as firing in a strict order.
Option B keeps
up{job="api"}andProbeDownhealthy, whilecanary_pipeline_check_total{result="skipped"}can appear before the five-minuteAnalyticsStreamDownalert. Rewrite this as option-dependent observations rather than claiming that the canary is always the slowest signal.🤖 Prompt for 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. In `@docs/exercises/03-break-the-event-stream.md` around lines 156 - 171, The signal comparison in the exercise incorrectly claims a strict firing order and that the canary is always slowest. Rewrite the affected explanation to describe option-dependent timing: under Option B, keep up{job="api"} and ProbeDown healthy, and note that canary_pipeline_check_total{result="skipped"} may appear before the five-minute AnalyticsStreamDown alert; preserve the distinction between canary_journey_total and the pipeline check.
🤖 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/exercises/00-baseline.md`:
- Around line 176-181: Update the explanation accompanying the docker compose
down -v command to explicitly warn that it deletes the Postgres volume and all
persisted database data, rather than only seeded rows or description-column
data.
In `@docs/exercises/01-monitoring-layers.md`:
- Around line 87-90: Update the CanaryJourneyFailing explanation to describe its
actual gauge-based condition: recent failures combined with elapsed time since
canary_journey_last_success_timestamp_seconds, followed by for: 5m. Remove the
incorrect rate(...) == 0 wording while preserving the comparison with ProbeDown
and the anti-flap tuning context.
- Around line 99-101: Reorder the cleanup verification in the exercise
instructions so the curl check for canary-prefixed items runs before make down
stops the backend. Keep make down as the final shutdown step after confirming no
canary items remain.
In `@docs/exercises/02-grpc-contract.md`:
- Around line 108-119: Update the examples and expected `buf breaking` result in
the “Run the same checks CI runs” section to describe failures under the
configured `FILE` policy, not wire incompatibility. Clarify that renaming
`GetItemStatsResponse.total_items` to `count` is a file-level change, and avoid
claiming the `Item.id` type change is wire-breaking; align the stated failure
behavior with `proto/buf.yaml`.
In `@docs/exercises/03-break-the-event-stream.md`:
- Around line 106-107: Make the outage-item count consistent in the exercise
instructions: either change the step to describe creating one item and keep the
single-item verification, or add a second POST and update the expected missing
aggregate count in the later verification. Apply the same correction to the
corresponding instructions around the later referenced section.
In `@docs/exercises/05-find-the-seeded-anomalies.md`:
- Around line 199-209: Qualify the scale-24 wording in the exercise discussion:
replace “no visible effect” with “may have no visible effect” and “structurally
unable” with “cannot reliably detect.” Preserve the explanation of non-zero
sampling probability and the existing distinction between gradual-degradation
and the short-lived traffic-spike or ingestion-outage anomalies.
In `@docs/exercises/06-watch-the-gc-sawtooth.md`:
- Around line 116-123: Update the report-ID extraction in the POST pipeline to
select the final path segment from the Location URL, yielding the actual report
ID rather than the host and port. Replace the single follow-up status request
with polling of the report endpoint until it reaches a terminal state before
reading status/error, while preserving the subsequent download-status check.
---
Outside diff comments:
In `@docs/exercises/03-break-the-event-stream.md`:
- Around line 156-171: The signal comparison in the exercise incorrectly claims
a strict firing order and that the canary is always slowest. Rewrite the
affected explanation to describe option-dependent timing: under Option B, keep
up{job="api"} and ProbeDown healthy, and note that
canary_pipeline_check_total{result="skipped"} may appear before the five-minute
AnalyticsStreamDown alert; preserve the distinction between canary_journey_total
and the pipeline check.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a5db21bf-901a-4e9a-9cc4-6ac4823a8940
📒 Files selected for processing (7)
docs/exercises/00-baseline.mddocs/exercises/01-monitoring-layers.mddocs/exercises/02-grpc-contract.mddocs/exercises/03-break-the-event-stream.mddocs/exercises/04-incident-to-inbox.mddocs/exercises/05-find-the-seeded-anomalies.mddocs/exercises/06-watch-the-gc-sawtooth.md
- 01: describe CanaryJourneyFailing's real condition (recent failures AND >60s since last success, a staleness gauge) instead of a nonexistent rate(...)==0; run the canary-item cleanup check while the stack is up, before make down stops the backend. - 02: buf uses the FILE policy (buf.yaml), so frame the failures as source/generated-code breakage -- a field rename and int32->int64 are wire-compatible yet break the generated API the consumer compiled against. - 03: create "one more item", matching the single-item outage verification. - 05: soften "structurally unable" / "no visible effect" to "cannot reliably" / "usually no visible effect" -- the text itself gives a non-zero chance a sample lands in the window. - 06: extract the report id as the Location's last path segment (robust to relative or absolute) and poll to a terminal state before asserting FAILED and the 409 download. - 00: make the down -v warning explicit -- it deletes the whole Postgres volume, not a narrow reset.
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/exercises/01-monitoring-layers.md`:
- Line 112: Update the shutdown command in the monitoring exercise documentation
to replace the literal “...” placeholder with the existing Docker Compose file
and project-directory arguments, producing a complete copy-pasteable command
while preserving the make down alternative.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 115f146e-cf23-49ab-820c-6756d87bc2ad
📒 Files selected for processing (6)
docs/exercises/00-baseline.mddocs/exercises/01-monitoring-layers.mddocs/exercises/02-grpc-contract.mddocs/exercises/03-break-the-event-stream.mddocs/exercises/05-find-the-seeded-anomalies.mddocs/exercises/06-watch-the-gc-sawtooth.md
🚧 Files skipped from review as they are similar to previous changes (5)
- docs/exercises/00-baseline.md
- docs/exercises/02-grpc-contract.md
- docs/exercises/03-break-the-event-stream.md
- docs/exercises/06-watch-the-gc-sawtooth.md
- docs/exercises/05-find-the-seeded-anomalies.md
Replace the copy-unfriendly `docker compose ... --profile "*" down` shorthand (literal ellipsis) with the full command in 01/03/04, matching the canonical invocation used elsewhere (PR #183 review).
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
1 participant
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.
Bring the exercises to one consistent, reality-first standard.
descriptionfield and operate it end to end. The hand-built ItemOut is the load-bearing trap: a green build, applied migration, and persisted column can still hide an API that never returns the field -- "done means operable", not 200.Summary by CodeRabbit