Crates.io Publication

Status: Current Last updated: 2026-09-06 03:03 EDT

Scope

The crates.io automation in this repo currently targets the Wave 1A foundation crates only. crates.io publication is a deliberate maintainer action, not a tag-triggered release path.

Wave 1A is:

1. talkbank-build
2. tree-sitter-talkbank
3. talkbank-derive
4. talkbank-model
5. talkbank-cache
6. talkbank-parser
7. talkbank-parser-re2c
8. talkbank-transform

talkbank-build is build-only support for the model and parser source fingerprints and must be published before those consumers.

talkbank-parser-re2c is part of the first wave because talkbank-transform has a runtime dependency on it. Holding it back would make talkbank-transform unpublishable.

Every workspace package outside Wave 1A must be explicitly marked publish = false. The check derives this complement from Cargo metadata, so a newly added crate cannot silently escape the publication decision. Application/API hold-backs include:

• send2clan
• chatter
• talkbank-lsp
• talkbank-llm

They stay blocked until their support contract, install story, and user-facing docs are ready. Internal test, vocabulary, desktop and task-runner packages are also checked; the script prints the complete current hold-back set.

What the repo now automates

Two repo-native entry points cover the first-wave foundations:

The readiness check enforces:

• required crates.io metadata (repository, homepage, keywords, categories, readme)
• readme-file existence
• package assembly for every first-wave crate via cargo package --list
• the first-wave runtime and build dependency graph
• publish = false guards on every workspace crate outside Wave 1A
• real cargo publish --dry-run checks for the standalone talkbank-build and tree-sitter-talkbank crates

The metadata-only mode uses locked Cargo metadata and reads README paths. It does not validate assembled package contents or registry resolution and cannot replace the full pre-publication check.

Important limitation: Cargo cannot fully dry-run the bootstrap wave

For the first publication of an interdependent workspace, cargo publish --dry-run is not a complete CI gate for every crate. Cargo rewrites path dependencies to registry dependencies while preparing the package. That means a crate such as talkbank-model cannot complete a registry-style dry-run until its prerequisite talkbank-derive already exists on crates.io.

So the current automation is intentionally honest:

• talkbank-build and tree-sitter-talkbank get real crates.io dry-runs because neither depends on an unpublished workspace crate.
• The remaining Wave 1A crates are validated by metadata, readme, and dependency checks before publication. (No MSRV is declared yet; set a deliberate rust-version and re-add an MSRV check when publication is actually pursued.)
• As each prerequisite crate lands on crates.io, rerun targeted cargo publish --dry-run -p <crate> checks for the later crates before publishing them.

This is a real limitation of the initial bootstrap wave, not a missing script. If we later want full registry-resolution rehearsal before publication, that requires a staging registry/local index strategy, not just another shell loop.

Publication procedure

Before publishing anything:

1. Verify crates.io name availability for every Wave 1A package.
2. Run just crates-io-foundation-check.
3. Ensure .github/workflows/crates-io-foundation.yml and the main CI workflow are green on the commit you intend to publish.
4. Publish in this exact order, waiting for the crates.io index to observe each crate before moving to the next:
   • tree-sitter-talkbank
   • talkbank-derive
   • talkbank-model
   • talkbank-cache
   • talkbank-parser
   • talkbank-parser-re2c
   • talkbank-transform
5. After each prerequisite becomes visible on crates.io, rerun any newly-unblocked cargo publish --dry-run -p <crate> checks before the next publish step.

Example command shape:

cargo publish -p tree-sitter-talkbank --locked

Tagging policy

Do not use version tags to drive crates.io publication from this repo. .github/workflows/release.yml is reserved for cargo-dist GitHub Releases of dist-enabled artifacts. Crates.io publication remains a deliberate manual maintainer flow.

This page last changed: 2026-09-06 (commit 45eb24a4). The whole book last changed: 2026-09-15 (commit bb4bef82).