docs(packaging): update workspace docs for three-crate split (#95 PR 4)#143
Conversation
Final step of the #95 split. After PRs 1-3 landed the code in the right crates, repo-level docs still described a two-crate (`shipper` + `shipper-cli`) layout and pointed install commands at `cargo install shipper-cli`. This PR brings the docs in line with what's actually on main. ## Updates - **`README.md`** — workspace crates section now shows the three-crate product surface: `shipper` (install), `shipper-cli` (CLI adapter), `shipper-core` (engine). - **`CLAUDE.md`** — replaces the two-crate description with the layered three-crate architecture, updates the build/test commands to target the right crates (`-p shipper-core` for engine work, `-p shipper-cli` for CLI work, `-p shipper` for façade tests), and explains where behavior / CLI / surface changes belong. - **`GEMINI.md`** — same architectural rewrite; project-structure section rewritten to match the new crate layout. - **`.github/copilot-instructions.md`** — rewritten to describe the three-crate shape, where work goes, and which paths to use in docs (`shipper_core::...` for engine internals, not `shipper::...`). - **`docs/structure.md`** — adds the three-crate diagram, replaces the `crates/shipper` module map with a `crates/shipper-core` map, and adds module maps for `shipper-cli` and the `shipper` façade. - **`docs/architecture.md`** — module path references (`shipper::engine`, `shipper::ops::auth`, `shipper::state::events`, etc.) rewritten to `shipper_core::...` so readers aren't chasing paths that no longer resolve from outside the façade. - **`docs/how-to/run-in-github-actions.md`** + **`templates/*.yml`** — `cargo install shipper-cli --locked` → `cargo install shipper --locked`. The old command still works (shipper-cli ships a compat binary), but the docs should push operators toward the product name. - **`crates/shipper-cli/README.md`** — rewritten to describe this crate as the CLI adapter (not "the CLI frontend over the shipper library"), with clear guidance on when to depend on `shipper-cli` vs `shipper-core` vs just installing `shipper`. ## What this PR does not do - Does not physically move the integration tests in `crates/shipper/tests/` into `crates/shipper-core/tests/`. They're still valid (they exercise the curated re-export surface) and moving them would double the churn in this PR for little gain. Flagged for a future cleanup if someone wants. - Does not touch `docs/decrating-plan.md` — that doc is historical and describes the absorption phase. Its `shipper::...` references are correct-at-the-time narrative, not operator-facing guidance. - Does not touch `RELEASE_NOTES_v0.2.0.md` (historical). ## Verification - `cargo check --workspace --all-targets` — clean - `cargo clippy --workspace --all-targets --all-features -- -D warnings` — clean Closes #95.
|
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 11 minutes and 24 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 (12)
✨ 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 restructures the repository into a three-crate architecture: shipper-core (engine), shipper-cli (CLI adapter), and shipper (install façade). Documentation, CI templates, and developer guides are updated to reflect this change and promote cargo install shipper as the primary installation method. Feedback was provided regarding an inconsistency in the total crate count mentioned across different documentation files.
| - Embedders add `shipper-core` to their `Cargo.toml` — no `clap`, no `indicatif`, no progress rendering pulled into their dep graph. | ||
| - The `shipper` library surface re-exports a curated subset of `shipper-core` (`engine`, `plan`, `types`, `config`, `state`, `store`) for drivers that prefer the product name. Engine internals reach through `shipper-core` directly. | ||
|
|
||
| All 13 workspace crates are published to crates.io. There is no separate "workspace-internal" tier — when a concern needs ownership, it lives as a module inside an owner crate (see [architecture.md](architecture.md)). |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Summary
Final step of the #95 split. After PRs 1-3 (#140, #141, #142) landed the code in the right crates, repo-level docs still described a two-crate (
shipper+shipper-cli) layout and pointed install commands atcargo install shipper-cli. This PR brings the docs in line with main.Updates
README.md— workspace crates section now shows the three-crate product surface.CLAUDE.md— three-crate architecture, updated build/test commands, where behavior/CLI/surface changes belong.GEMINI.md— same architectural rewrite; project-structure section updated for the new layout..github/copilot-instructions.md— rewritten to describe the three-crate shape and which paths to use in docs.docs/structure.md— three-crate diagram,crates/shipper-coremodule map, plus module maps forshipper-cliand theshipperfaçade.docs/architecture.md—shipper::Xpath references rewritten toshipper_core::Xso readers aren't chasing paths that no longer resolve from outside the façade.docs/how-to/run-in-github-actions.md+templates/*.yml—cargo install shipper-cli --locked→cargo install shipper --locked.crates/shipper-cli/README.md— rewritten to describe this crate as the CLI adapter, with guidance on when to depend onshipper-clivsshipper-corevs just installingshipper.What this PR does not do
crates/shipper/tests/intocrates/shipper-core/tests/. They exercise the curated re-export surface and moving them would double the churn here for little gain. Flagged for future cleanup.docs/decrating-plan.md(historical narrative).Verification
cargo check --workspace --all-targets— cleancargo clippy --workspace --all-targets --all-features -- -D warnings— cleanCloses #95.
Test plan