Skip to content

docs(readme): rewrite the four user-facing READMEs as a coherent family#152

Merged
EffortlessSteven merged 2 commits into
mainfrom
docs/readme-rewrite
Apr 19, 2026
Merged

docs(readme): rewrite the four user-facing READMEs as a coherent family#152
EffortlessSteven merged 2 commits into
mainfrom
docs/readme-rewrite

Conversation

@EffortlessSteven

@EffortlessSteven EffortlessSteven commented Apr 19, 2026

Copy link
Copy Markdown
Member

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

File Job
README.md ROUTE — problem, one quick-start, boundary, links into Diátaxis docs
crates/shipper/README.md INSTALL FACE — what crates.io viewers see for the install target
crates/shipper-core/README.md SDK PAGE — when to embed, what lives here, minimal code sketch
crates/shipper-cli/README.md ADAPTER PAGE — shortest; tells readers to install shipper first

Steering docs — aligned with the new READMEs

File Change
docs/product.md Dropped stale What'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.md Dropped rc.1 baseline framing and hardcoded tag commands; replaced with VERSION=$(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 landing

What got cut (from all six files)

  • Dated release-history prose (v0.3.0-rc.1 shipped 2026-04-16…)
  • Runtime metrics (41 retries, 69-minute run, 12 crates live)
  • Audience matrix on the root
  • Full command catalogs
  • Long architecture walkthroughs
  • Config/auth/CI deep reference (those live in their own docs)
  • shipper-cli as "compatibility shim" wording — it's the real adapter

What got added / grew

  • shipper-core README went 25 → 65 lines (it was too thin — now a proper embedder onboarding with when/what/what-not/minimal sketch).
  • docs/release-runbook.md now re-runnable for rc.3, 0.3.0 stable, 0.4.0 etc. without edits — VERSION pulled from Cargo.toml at release time.

Numbers

  • READMEs: 497 → 219 lines (≈56% reduction) across the four files.
  • Intentional single version-pinned link preserved (release-v0.3.0-rc.1-manifest.md kept as a historical artifact, reframed as such in the runbook prose).

Test plan

  • cargo check --workspace clean
  • grep -rn "compatibility shim" in the rewritten files → no hits
  • grep -rn "v0.3.0-rc.1 shipped" in the rewritten files → no hits
  • Cross-references between READMEs and steering docs all resolve to correct crates/paths
  • release-runbook.md tag-cut commands use VERSION= pattern, not hardcoded

Still out of scope (future cleanup)

  • docs/reference/state-files.md — example snippets use 0.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).

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.
@coderabbitai

coderabbitai Bot commented Apr 19, 2026

Copy link
Copy Markdown

Warning

Rate limit exceeded

@EffortlessSteven has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 37 seconds before requesting another review.

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 @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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 configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 687c77e9-ab55-4163-8898-ff012c7d879f

📥 Commits

Reviewing files that changed from the base of the PR and between 8254a58 and 9ab0f53.

📒 Files selected for processing (6)
  • README.md
  • crates/shipper-cli/README.md
  • crates/shipper-core/README.md
  • crates/shipper/README.md
  • docs/product.md
  • docs/release-runbook.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/readme-rewrite

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

codecov Bot commented Apr 19, 2026

Copy link
Copy Markdown

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.
@EffortlessSteven EffortlessSteven merged commit 25e23ad into main Apr 19, 2026
20 checks passed
@EffortlessSteven EffortlessSteven deleted the docs/readme-rewrite branch April 19, 2026 09:36
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