Skip to content

[freeze] Publish-readiness: crates.io names (reserve now), version tiers, docs.rs config, per-crate READMEs #280

Description

@joeldsouzax

Problem

"Done" currently means frozen-in-a-private-repo. Bombay M2 (the nexus runtime adapter), agency, and any external adopter need a versioned crates.io dependency — git pins don't survive a public launch, and the B1 reach-first strategy (OSS distribution, agency #142) starts with cargo add.

#221 covers fixing release-plz mechanics. This card is everything else publish-readiness needs, and it has freeze-adjacent pieces (names and feature defaults are effectively API):

Work

  • Name check & reservation. nexus on crates.io is almost certainly taken (cesr had the same problem → published as cesr-rs with [lib] name = "cesr"). Decide the published names for nexus, nexus-store, nexus-macros, nexus-fjall, nexus-postgres, nexus-store-testing (same -rs suffix trick keeps import paths clean) and reserve them NOW — squatting risk is real and grows with every public mention.
  • Version strategy. Which crates cut 1.0 vs stay 0.x? Recommendation: kernel + nexus-store go 1.0 (that's what the freeze freezes); adapters (fjall/postgres) stay 0.x so storage iteration doesn't force major bumps.
  • Package metadata: description, keywords, categories, repository/homepage, rust-version in every publishable Cargo.toml.
  • docs.rs config: [package.metadata.docs.rs] all-features (or curated feature set) per crate so the GAT/feature-gated surface actually renders.
  • Per-crate README (crates.io shows it): 30-second quickstart, feature matrix, MSRV, link to the narrative docs (docs: host nexus narrative docs the kameo way (docs.page) #223).
  • workspace-hack: confirm publish = false and that hakari doesn't leak into published manifests.
  • Dry-run: cargo publish --dry-run green for every crate in dependency order.

Acceptance

cargo add <published-name> works from a clean machine; docs.rs renders all public items; release-plz (#221) cuts the next release without hand-holding.

From the 2026-07-05 cross-repo roadmap review (ROADMAP.md Phase 0).

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: metarepo-wide (build/toolchain/deps/CI)

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions