Why
Now that the 6 crates of the UFFS publishable subset all ship per-crate README.md files (uffs-time + uffs-text via #237, uffs-mft + uffs-client + uffs-mcp + uffs-cli via #239) and #238 will land the manifest-audit allow-list mechanism that permits a per-crate readme = "README.md" override, there is one outstanding cosmetic warning left on the packaging path:
warning: readme `../../README.md` appears to be a path outside of the package,
but there is already a file named `README.md` in the root of the package.
The archived crate will contain the copy in the root of the package.
Update the readme to point to the path relative to the root of the package
to remove this warning.
This warning fires on every cargo package -p <crate> --list for every publishable crate. The archived crate is correct — cargo ships the local README.md — but the warning is noisy in CI logs and in dry-run publish output.
What
After #238 merges, a single small PR (≤ 15 lines net change):
- Extend
KnownExceptions::readme_override_ok from 2 to 6 entries in scripts/ci/manifest-audit/src/audit.rs. Today the allow-list seeds with uffs-time + uffs-text; add uffs-mft, uffs-client, uffs-mcp, uffs-cli.
- Replace
readme.workspace = true with readme = "README.md" + the standard rationale comment on each of the 6 publishable crates' Cargo.toml:
crates/uffs-time/Cargo.toml
crates/uffs-text/Cargo.toml
crates/uffs-mft/Cargo.toml
crates/uffs-client/Cargo.toml
crates/uffs-mcp/Cargo.toml
crates/uffs-cli/Cargo.toml
The rationale comment template (used on PR #237's first draft before it was reverted pending #238):
# Per-crate README override. The workspace-level `readme = "README.md"`
# (see root `Cargo.toml`'s `[workspace.package]`) resolves to the app-
# focused workspace-root README when inherited here, which is the wrong
# artifact for this library crate's crates.io detail page. Explicit
# override means the crate's own `README.md` (alongside this manifest)
# is what gets shipped in the published `.crate` and rendered on
# crates.io / docs.rs, and silences the `cargo package` warning about
# `../../README.md` being outside the package.
#
# Permitted by manifest-audit invariant 3.5 via
# `KnownExceptions::readme_override_ok` — see
# `scripts/ci/manifest-audit/src/audit.rs` for the allow-list contract.
readme = "README.md"
Verification (planned for the follow-up PR)
cargo package -p <crate> --list --allow-dirty on all 6 — README.md still in the archive, no warning emitted.
cargo run -p uffs-manifest-audit — zero findings.
- All pre-push gates pass.
Acceptance criteria
Priority
Low / purely cosmetic. The warning has zero functional impact — every README.md is correctly shipped today. This issue collapses the warning at the source for a cleaner publish dry-run experience.
Dependencies
Out of scope
- Changing the workspace-level
readme = "README.md" setting in root Cargo.toml. That setting is correct for non-publishable crates that inherit and would otherwise have no README. Per-crate override is the right escape hatch for publishable crates with their own README.
- Adding more entries to
readme_override_ok for non-publishable crates. The 6-crate seed reflects the exact post-scrub publishable subset; any future additions track the publishable-set decisions documented in docs/refactor/crates-io-publishability-deep-dive.md.
Why
Now that the 6 crates of the UFFS publishable subset all ship per-crate
README.mdfiles (uffs-time+uffs-textvia #237,uffs-mft+uffs-client+uffs-mcp+uffs-clivia #239) and #238 will land the manifest-audit allow-list mechanism that permits a per-cratereadme = "README.md"override, there is one outstanding cosmetic warning left on the packaging path:This warning fires on every
cargo package -p <crate> --listfor every publishable crate. The archived crate is correct — cargo ships the localREADME.md— but the warning is noisy in CI logs and in dry-run publish output.What
After #238 merges, a single small PR (≤ 15 lines net change):
KnownExceptions::readme_override_okfrom 2 to 6 entries inscripts/ci/manifest-audit/src/audit.rs. Today the allow-list seeds withuffs-time+uffs-text; adduffs-mft,uffs-client,uffs-mcp,uffs-cli.readme.workspace = truewithreadme = "README.md"+ the standard rationale comment on each of the 6 publishable crates'Cargo.toml:crates/uffs-time/Cargo.tomlcrates/uffs-text/Cargo.tomlcrates/uffs-mft/Cargo.tomlcrates/uffs-client/Cargo.tomlcrates/uffs-mcp/Cargo.tomlcrates/uffs-cli/Cargo.tomlThe rationale comment template (used on PR #237's first draft before it was reverted pending #238):
Verification (planned for the follow-up PR)
cargo package -p <crate> --list --allow-dirtyon all 6 —README.mdstill in the archive, no warning emitted.cargo run -p uffs-manifest-audit— zero findings.Acceptance criteria
readme = "README.md"(notreadme.workspace = true).KnownExceptions::readme_override_okcontains exactly the 6 publishable crates.cargo package -p <crate>emits zero readme-related warnings for each of the 6 crates.Priority
Low / purely cosmetic. The warning has zero functional impact — every
README.mdis correctly shipped today. This issue collapses the warning at the source for a cleaner publish dry-run experience.Dependencies
Out of scope
readme = "README.md"setting in rootCargo.toml. That setting is correct for non-publishable crates that inherit and would otherwise have no README. Per-crate override is the right escape hatch for publishable crates with their own README.readme_override_okfor non-publishable crates. The 6-crate seed reflects the exact post-scrub publishable subset; any future additions track the publishable-set decisions documented indocs/refactor/crates-io-publishability-deep-dive.md.