Skip to content

docs(rust): rewrite the README as a crates.io landing page - #207

Open
lan17 wants to merge 1 commit into
mainfrom
claude/rust-readme-english-audit-c4b8f6
Open

lan17 wants to merge 1 commit into
mainfrom
claude/rust-readme-english-audit-c4b8f6

Conversation

@lan17

@lan17 lan17 commented Sep 22, 2026

Copy link
Copy Markdown
Owner

rust/README.md is what crates.io renders for the dialcache crate, and until now it never said how to install it. This rewrite gives the Rust README the shape of the TypeScript README and makes every fact scannable for an engineer evaluating the crate.

  • Open with the use-case definition, the experimental notice, nine capability bullets (all under 80 columns) and one link line that includes docs.rs.
  • Add an Install section: cargo add, a feature table, and the MSRV rule (1.85; 1.88 for the redis feature because of the locked redis 1.x dependency).
  • Show both entry points in the Usage snippet (use_case().register() and get_or_load) plus get_uncached, followed by five gotcha bullets.
  • Replace fact-list paragraphs with tables for Policy leaves and instance defaults; every paragraph is one idea and under 60 words.
  • Remove protocol-internal terms (request memo, flight, settlement, quiescence) and second person; name the real builder knob shadow_max_in_flight instead of "shadow capacity".
  • Move contributor-only details (settlement control, driver causality, DIALCACHE_RUST_SUITE) out; they live in formal/PORTING.md and formal/WALKTHROUGH.md.

Validation: the Usage snippet was extracted into a temporary example and passed cargo check, rustfmt --check and cargo run (asserts hold; it prints Hello, User 42 <ada@example.com>!). All 17 links and 3 heading anchors resolve. Every factual claim was re-checked against rust/src (defaults in limits.rs, builder methods, Error variants, Policy::validate, feature gates) and the locked redis crate's rust-version.

Scope: README prose only. No code, Quint model, conformance assertion or docs-site page changed. rust/README.md is not part of the source audit, so no ledger refresh is needed. Prose length is unchanged at about 2,070 words; readability comes from structure, not deletion.

rust/README.md is what crates.io renders for the dialcache crate, and it
never said how to install the crate. This rewrite gives it the shape of the
TypeScript README and makes every fact scannable.

- Open with the use-case definition, the experimental notice, nine capability
  bullets and one link line that includes docs.rs.
- Add an Install section: cargo add, a feature table, and the MSRV rule
  (1.85; 1.88 for the redis feature because of the locked redis 1.x).
- Show both entry points in the Usage snippet (use_case().register() and
  get_or_load) plus get_uncached; the snippet compiles, passes rustfmt and
  runs. Follow it with five gotcha bullets.
- Replace fact-list paragraphs with tables for Policy leaves and instance
  defaults, and keep every paragraph under 60 words and one idea.
- Remove protocol-internal terms (request memo, flight, settlement,
  quiescence) and second person; name the real builder knob
  shadow_max_in_flight instead of "shadow capacity".
- Move contributor-only details (settlement control, driver causality) out;
  they live in formal/PORTING.md and formal/WALKTHROUGH.md.

All 17 links and 3 heading anchors verified. No prose line exceeds 80
columns. Prose length is unchanged (about 2,070 words); readability comes
from structure, not deletion.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant