Publishing on crates.io
The library team wrote a tidy little crate that checks shelf codes like F-120. Another library wants to use it. Publishing it on crates.io, Rust's public registry, lets anyone add it with one line, and it comes with one promise you cannot take back.
The rule
Describe it, dry-run it, publish it: every version is permanent.
1. Describe it. crates.io refuses a package without a description and a license. The name must not already be taken; names are first come, first served.
[package]
name = "shelf-codes"
version = "0.1.0"
edition = "2021"
description = "Parse and validate library shelf codes such as F-120"
license = "MIT OR Apache-2.0"
repository = "https://github.com/example/shelf-codes"
readme = "README.md"
keywords = ["library", "parser"]Write doc comments (///) on public items; docs.rs builds your documentation automatically after publishing.
2. Log in once. Sign in to crates.io, create an API token, then:
cargo login # paste the token when asked3. Dry-run, then publish.
cargo publish --dry-run # builds the package exactly as it would upload
cargo publishThe permanence rule. A version, once published, can never be overwritten. To fix a bug you publish a new version. Follow semantic versioning: patch (0.1.0 → 0.1.1) for fixes, minor for new features, major for breaking changes, remembering that below 1.0 a minor bump counts as breaking.
Yanking a bad version:
cargo yank --version 0.1.0This stops new lock files from choosing 0.1.0. It does not delete the code, and projects whose Cargo.lock already names 0.1.0 still build. Treat anything you publish, including an accidentally committed secret, as public forever.
The shortcut
Before every publish, run a four-word check: name, metadata, version, dry-run.
Name
Already ours from 0.1.0. A first release would check the name is free.
Drills
Answer fast — trust the rule.
Which two Cargo.toml fields does crates.io require before publishing?
You found a bug in published version 0.3.0. What do you do?
What does cargo yank --version 0.3.0 do?
What does cargo publish --dry-run do?
Remember
- Add
descriptionandlicense, log in with a token,--dry-run, thencargo publish. - Check: name, metadata, version, dry-run.
- Versions are permanent; fix forward with a new version, and yanking only hides.