docs(readme): restructure for readers; move the limitations list to docs/LIMITATIONS.md - #338
Merged
Conversation
…ocs/LIMITATIONS.md The README grew with the crate — 482 lines, four long paragraphs where a table would do, a 130-line limitations list ahead of the MSRV, and a diagram that named wait_idle as the primary wait. It now reads in the order a new reader asks questions: why, quick start, how it works, which wait, snapshots, what a test can see, CLI and CI, comparison, platforms, stability, limitations, agents, documentation map, contributing. The architecture diagram is redrawn left to right with three lanes — your test, termlens, the kernel and your application — in a palette that holds on both GitHub themes (subgraph fills are none, node text is explicit white), and its labels name the waits the docs recommend. The full limitations list moves verbatim to docs/LIMITATIONS.md, grouped under nine headings, and STABILITY.md §1 now points there; the README keeps a seven-line summary. Facts checked against the source: every accessor named exists, every linked file exists, the report action pin is v0.10.1 in both READMEs, defaults (1,000 rows, 8 frames) match the constants. The quick-start example is unchanged and still mirrors tests/readme_example.rs. The stability section states 0.11 as the candidate and links the 1.0 criteria in #335. Signed-off-by: Vyncint Ng <115854244+vyncint@users.noreply.github.com>
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.
A documentation-only restructuring of the README, 482 → 359 lines, plus a new
docs/LIMITATIONS.md.Structure. The README now follows the order a new reader asks questions: why → quick start → how it works → which wait → snapshots → what a test can see → CLI and CI → comparison → platform support → stability and versioning → limitations → coding agents → documentation map → contributing → license. Four long prose paragraphs became three tables (waits, observables, platforms); the licence rationale and the determinism essay are trimmed to what a reader needs, with DESIGN §2 linked for the rest.
Diagram. Redrawn left-to-right in three lanes — your test / termlens / kernel + your application — with a palette that holds on both GitHub themes (no subgraph fills; explicit white node text) and labels that name the waits the docs recommend (
wait_until,wait_frame,snapshot_after) rather thanwait_idle.Limitations. The full list moves verbatim to
docs/LIMITATIONS.md, grouped under nine headings (16 entries before and after).STABILITY.md§1's "the README's Known limitations carry the user-facing list" now points there. The README keeps a seven-line summary.Facts checked against the source: every accessor named in the tables exists (
pub fngrep); every linked file and in-page anchor exists; the report action pin isv0.10.1in the README and in.github/actions/report/README.md(wasv0.10.0); defaults quoted (1,000 scrollback rows, 8 frames) match the constants. The quick-start example is byte-identical and still mirrorstests/readme_example.rs. The stability section states 0.11 as the candidate and links #335.No code changes.
Cargo.toml'sreadmepath is unchanged; note that crates.io does not render Mermaid, so the prose under the diagram is written to stand on its own.Signed-off-by: Vyncint Ng 115854244+vyncint@users.noreply.github.com