Skip to content

chore(publish): apply per-crate readme override on all 6 publishable crates (silence cargo package warning) #240

@githubrobbi

Description

@githubrobbi

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):

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

  • All 6 publishable crates carry readme = "README.md" (not readme.workspace = true).
  • KnownExceptions::readme_override_ok contains exactly the 6 publishable crates.
  • cargo package -p <crate> emits zero readme-related warnings for each of the 6 crates.
  • manifest-audit reports zero findings.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions