docs(readme): rewrite the four user-facing READMEs as a coherent family#152
Conversation
Each of the four READMEs was trying to do too many jobs (pitch, status bulletin, reference, architecture, examples, changelog), which made the landing pages stale, bloated, and internally inconsistent with the three-crate product story that #95 landed. This rewrite aligns them around one job per page. Role allocation after this PR: - README.md (root) — ROUTE. Problem statement, one quick-start, one "what Shipper doesn't do" boundary, links into Diátaxis docs. No release-history prose, no runtime metrics, no audience matrix, no config/CI walkthrough — those live in their own docs. - crates/shipper/README.md — INSTALL FACE. What users see on crates.io for the install target. Problem, install, four-command quick-start, pointer to the sibling crates for lean embedding. - crates/shipper-core/README.md — SDK PAGE. Grew from a 25-line positioning note to a proper embedder onboarding: when to pick it, what lives here, what doesn't, the API shape to expect, and a minimal code sketch. - crates/shipper-cli/README.md — ADAPTER PAGE. Deliberately the shortest. Tells users to install `shipper` first, shows when to reach for the adapter directly (custom wrappers, explicit install of `shipper-cli`), points lean embedders at `shipper-core`. Cut stable across all four: dated release-history prose, 41-retries / 69-minute run metrics, audience matrix, full command catalogs, long architecture narration. Those belong in CHANGELOG.md, roadmap, and the Diátaxis docs tree — not on landing pages. Totals: 497 → 219 lines (≈56% reduction) across the four files, while `shipper-core` actually grew because it was too thin before. Verified: - cargo check --workspace clean - grep for "compatibility shim" / rc.1 release prose / stale install commands returns no hits in the rewritten files. Follow-on: docs/release-runbook.md and docs/product.md still carry stale rc.1 references — out of scope for this PR; will follow in separate doc-cleanup work.
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 1 minutes and 37 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, 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 have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (6)
✨ 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 |
There was a problem hiding this comment.
Code Review
This pull request refactors the documentation across the workspace to align with the three-crate architecture (shipper, shipper-cli, and shipper-core). The README files have been streamlined to clearly distinguish between the installable product, the CLI adapter, and the lean engine library, providing better guidance on which crate to use based on the user's needs. I have no feedback to provide as the changes correctly reflect the project structure and improve documentation clarity.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…lity Follow-on from the four-README rewrite. Two agents did the heavy lifting; this commit lands their work. docs/product.md: - Dropped the stale `What's shipped (v0.3.0-rc.1)` capability-status table (rows were either outdated or duplicated ROADMAP content). - Added a three-crate Product Shape section matching the new READMEs (shipper = install face, shipper-cli = adapter, shipper-core = engine). - Added a concise What Shipper Does Today section naming each of the nine competencies as present capabilities, pointing at ROADMAP for status and CHANGELOG for per-release detail instead of duplicating. - Expanded Compared to alternatives to include cargo publish --workspace (Cargo 1.90+). - Rewrote the Where to go from here table as role-based navigation, including an embedder row pointing at shipper-core. - Kept the identity sentence, the "intentionally narrow" framing, and the audience paragraph pattern — those were already steering-shaped. docs/release-runbook.md: - Dropped the `Current RC baseline: v0.3.0-rc.1 / 5beab9b` framing and the hardcoded `git tag -a v0.3.0-rc.1` example. - Replaced with a VERSION=$(cargo metadata...) pattern so operators tag from Cargo.toml rather than hardcoding per-release. - Updated crates-in-the-train to 13 with the new tier structure (tier 4 core → tier 5 cli → tier 6 install façade). - Reframed auth as "token fallback (primary today) / Trusted Publishing (target path)", matching what PR #150 actually landed and the live state of the crates.io-side TP registration. - Rewrote walk-back section to lead with `shipper plan-yank` / `shipper fix-forward`, manual `cargo yank` as fallback. - Deliberately kept the single link to release-v0.3.0-rc.1-manifest.md and the "as of rc.2" capability signal — both are intentionally version-pinned historical markers. Totals: docs/product.md 530 words, docs/release-runbook.md ~250 lines of version-agnostic procedure the operator can re-run for rc.3, 0.3.0 stable, 0.4.0, etc. without edits.
Summary
Rewrites the four user-facing READMEs so each has one job instead of trying to be product pitch + status bulletin + reference + architecture all at once. Extends the same alignment pass to two steering docs.
Files rewritten (6)
READMEs — four-file family with one job each
README.mdcrates/shipper/README.mdcrates/shipper-core/README.mdcrates/shipper-cli/README.mdshipperfirstSteering docs — aligned with the new READMEs
docs/product.mdWhat's shipped (v0.3.0-rc.1)table; added three-crate Product Shape; reworked nine-competency section as present capabilities (not a scorecard); expanded alternatives table for Cargo 1.90+docs/release-runbook.mdrc.1 baselineframing and hardcoded tag commands; replaced withVERSION=$(cargo metadata…)pattern; 13-crate tier structure with the three-crate split; auth section reframed as "token fallback primary today / Trusted Publishing target path" matching PR #150's actual landingWhat got cut (from all six files)
v0.3.0-rc.1 shipped 2026-04-16…)41 retries,69-minute run,12 crates live)shipper-clias "compatibility shim" wording — it's the real adapterWhat got added / grew
shipper-coreREADME went 25 → 65 lines (it was too thin — now a proper embedder onboarding with when/what/what-not/minimal sketch).docs/release-runbook.mdnow re-runnable for rc.3, 0.3.0 stable, 0.4.0 etc. without edits —VERSIONpulled fromCargo.tomlat release time.Numbers
release-v0.3.0-rc.1-manifest.mdkept as a historical artifact, reframed as such in the runbook prose).Test plan
cargo check --workspacecleangrep -rn "compatibility shim"in the rewritten files → no hitsgrep -rn "v0.3.0-rc.1 shipped"in the rewritten files → no hitsrelease-runbook.mdtag-cut commands useVERSION=pattern, not hardcodedStill out of scope (future cleanup)
docs/reference/state-files.md— example snippets use0.3.0-rc.1. Purely illustrative; not blocking.docs/decrating-plan.md— version strings in an illustrative example block from the rc.1 era. Historical plan doc.docs/explanation/finishability.md/docs/INVARIANTS.md— intentionally reference rc.1 as a specific historical incident (appropriate to pin).