mirror of
https://github.com/logos-blockchain/logos-blockchain-testing.git
synced 2026-01-02 13:23:13 +00:00
71 lines
2.6 KiB
Markdown
71 lines
2.6 KiB
Markdown
|
# Book → Repo Sync Review (2025-12-20)
|
|||
|
|
|
|||
|
|
Reviewed against `git rev-parse HEAD` at the time of writing, plus local working tree changes.
|
|||
|
|
|
|||
|
|
## Checks Run
|
|||
|
|
|
|||
|
|
- `mdbook build book`
|
|||
|
|
- `mdbook test book`
|
|||
|
|
- `cargo build -p doc-snippets`
|
|||
|
|
- Verified `book/src/SUMMARY.md` covers all pages in `book/src/` (no orphaned pages)
|
|||
|
|
- Verified all `scripts/...` paths referenced from the book exist
|
|||
|
|
- Compared `NOMOS_*` environment variables used in `scripts/`, `testing-framework/`, and `examples/` vs. `book/src/environment-variables.md`
|
|||
|
|
|
|||
|
|
## Findings / Fixes Applied
|
|||
|
|
|
|||
|
|
- `book/src/environment-variables.md` was not a complete reference: it missed multiple `NOMOS_*` variables used by the repo (scripts + framework). Added the missing variables and corrected a misleading note about `RUST_LOG` vs node logging.
|
|||
|
|
- `book/src/running-examples.md` “Quick Smoke Matrix” section didn’t reflect current `scripts/run/run-test-matrix.sh` flags. Added the commonly used options and clarified the relationship to `NOMOS_SKIP_IMAGE_BUILD`.
|
|||
|
|
- `book/src/part-iv.md` existed but was not in `book/src/SUMMARY.md`. Removed it so the rendered book doesn’t silently diverge from the filesystem.
|
|||
|
|
- `mdbook test book` was failing because:
|
|||
|
|
- Many Rust examples were written as ` ```rust` (doctested by default) but depend on workspace crates; they aren’t standalone doctest snippets.
|
|||
|
|
- Several unlabeled code blocks (e.g. tree/log output) were treated as Rust by rustdoc.
|
|||
|
|
- Updated code fences to ` ```rust,ignore` for non-standalone Rust examples and to ` ```text` for non-Rust output blocks so `mdbook test book` succeeds.
|
|||
|
|
|
|||
|
|
## Pages Reviewed (No Skips)
|
|||
|
|
|
|||
|
|
All pages under `book/src/` currently included by `book/src/SUMMARY.md`:
|
|||
|
|
|
|||
|
|
- `annotated-tree.md`
|
|||
|
|
- `api-levels.md`
|
|||
|
|
- `architecture-overview.md`
|
|||
|
|
- `authoring-scenarios.md`
|
|||
|
|
- `best-practices.md`
|
|||
|
|
- `chaos.md`
|
|||
|
|
- `ci-integration.md`
|
|||
|
|
- `custom-workload-example.md`
|
|||
|
|
- `design-rationale.md`
|
|||
|
|
- `dsl-cheat-sheet.md`
|
|||
|
|
- `environment-variables.md`
|
|||
|
|
- `examples-advanced.md`
|
|||
|
|
- `examples.md`
|
|||
|
|
- `extending.md`
|
|||
|
|
- `faq.md`
|
|||
|
|
- `glossary.md`
|
|||
|
|
- `internal-crate-reference.md`
|
|||
|
|
- `introduction.md`
|
|||
|
|
- `logging-observability.md`
|
|||
|
|
- `node-control.md`
|
|||
|
|
- `operations-overview.md`
|
|||
|
|
- `part-i.md`
|
|||
|
|
- `part-ii.md`
|
|||
|
|
- `part-iii.md`
|
|||
|
|
- `part-v.md`
|
|||
|
|
- `part-vi.md`
|
|||
|
|
- `prerequisites.md`
|
|||
|
|
- `project-context-primer.md`
|
|||
|
|
- `quickstart.md`
|
|||
|
|
- `runners.md`
|
|||
|
|
- `running-examples.md`
|
|||
|
|
- `running-scenarios.md`
|
|||
|
|
- `scenario-builder-ext-patterns.md`
|
|||
|
|
- `scenario-lifecycle.md`
|
|||
|
|
- `scenario-model.md`
|
|||
|
|
- `testing-philosophy.md`
|
|||
|
|
- `topology-chaos.md`
|
|||
|
|
- `troubleshooting.md`
|
|||
|
|
- `usage-patterns.md`
|
|||
|
|
- `what-you-will-learn.md`
|
|||
|
|
- `workloads.md`
|
|||
|
|
- `workspace-layout.md`
|
|||
|
|
|