Skip to content

docs(packaging): update workspace docs for three-crate split (#95 PR 4)#143

Merged
EffortlessSteven merged 1 commit into
mainfrom
feat/95-pr4-docs-sweep
Apr 18, 2026
Merged

docs(packaging): update workspace docs for three-crate split (#95 PR 4)#143
EffortlessSteven merged 1 commit into
mainfrom
feat/95-pr4-docs-sweep

Conversation

@EffortlessSteven

Copy link
Copy Markdown
Member

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 at cargo 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-core module map, plus module maps for shipper-cli and the shipper façade.
  • docs/architecture.mdshipper::X path references rewritten to shipper_core::X so readers aren't chasing paths that no longer resolve from outside the façade.
  • docs/how-to/run-in-github-actions.md + templates/*.ymlcargo install shipper-cli --lockedcargo install shipper --locked.
  • crates/shipper-cli/README.md — rewritten to describe this crate as the CLI adapter, with 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 crates/shipper/tests/ into crates/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.
  • Does not touch docs/decrating-plan.md (historical narrative).

Verification

  • cargo check --workspace --all-targets — clean
  • cargo clippy --workspace --all-targets --all-features -- -D warnings — clean

Closes #95.

Test plan

  • cargo check --workspace --all-targets
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • CI green on all matrices

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

coderabbitai Bot commented Apr 18, 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 11 minutes and 24 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 11 minutes and 24 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: 116cb6b4-56ac-41bd-947e-77358c27965d

📥 Commits

Reviewing files that changed from the base of the PR and between 65782d5 and 1f2f5b7.

📒 Files selected for processing (12)
  • .github/copilot-instructions.md
  • CLAUDE.md
  • GEMINI.md
  • README.md
  • crates/shipper-cli/README.md
  • docs/architecture.md
  • docs/how-to/run-in-github-actions.md
  • docs/structure.md
  • templates/azure-pipelines.yml
  • templates/circleci-config.yml
  • templates/github-trusted-publishing.yml
  • templates/gitlab-publish.yml
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/95-pr4-docs-sweep

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

Comment thread docs/structure.md
- 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)).

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

medium

The crate count has been updated to 13 here to reflect the new three-crate split, but docs/architecture.md (line 30) and README.md (line 13) still refer to 12 crates. Please ensure the total crate count is consistent across all documentation files.

@EffortlessSteven EffortlessSteven merged commit 5322a89 into main Apr 18, 2026
19 checks passed
@EffortlessSteven EffortlessSteven deleted the feat/95-pr4-docs-sweep branch April 18, 2026 15:32
@codecov

codecov Bot commented Apr 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

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.

Packaging UX: make 'cargo install shipper' work by collapsing binary into shipper package

1 participant