docs: give every workspace member its own README - #21
Merged
Conversation
crates.io renders each crate's own README, and all 16 published crates had none — their pages showed a bare description with no usage, no link back to the workspace, and no way to tell a shipping handler from a detection-only stub. Each now carries its purpose, install snippet, public surface and the caveats specific to it, with `readme` declared explicitly rather than left to filename auto-detection. Fixes a false claim in the root README while in there: it told readers to `cargo install pxsolver-server pxsolver-cli`, but both binaries are `publish = false` and have never been on crates.io. Only the 16 library crates are published; the binaries build from source. The root README now lists what is actually installable from where. Also documents the package/crate name split — you depend on `pxsolver-core` but `use px_core::…`, which is not guessable from the crates.io page alone. px-server, px-cli and xtask are unpublished but get READMEs too; they are what a reader browsing the repo lands on.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
crates.io renders each crate's own README, and all 16 published
pxsolver-*crates had none. Their pages showed a one-line description and nothing else — no usage, no link back to the workspace, and no way to tell a shipping handler (pxsolver-perimeterx) from a detection-only stub (pxsolver-turnstile).What's here
pxsolver-harvester, the rotation math forpxsolver-camoufox, stub status for the three placeholder handlers, the v1.9.0 signature change forpxsolver-pipeline).readme = "README.md"declared explicitly on the 16 published crates rather than relying on filename auto-detection.pxsolver-corebut youuse px_core::…. Not guessable from a crates.io page.Bug fixed on the way
The root README told readers to run:
Both are
publish = falseand have never existed on crates.io — that command fails. Only the 16 library crates are published; the binaries build from source. The root README now lists what is actually installable and from where, with a table of the published crates.These do not reach crates.io until the next minor
1.9.0 is already published and versions are immutable, so the crate pages stay bare until a new version ships. Per
.github/workflows/release.yml, the crates.io publish is gated on minor/major/initial — a patch tag will not publish. Surfacing these needs a 1.10.0.Verification
cargo check --workspace --all-targetsclean ·cargo package -p pxsolver-core --listconfirmsREADME.mdis included in the packaged artifact. Docs and manifest metadata only; no code paths touched.