ruk·si
/notes

🦀 Rust
Releases

Updated at 2025-03-24 04:53

You generally release your Rust library crates to a registry like crates.io.

For crates that should never be released to registries like crates.io, mark the crate specifically not to be published

[package]
publish = false

This same field is used to define alternative registries to publish to.

To make releasing easier, I prefer to use cargo-release

cargo install cargo-release --locked

Configure the release process to your liking, like:

[workspace.metadata.release]
shared-version = true
pre-release-commit-message = "🔖 Become {{version}}"
tag-name = "v{{version}}"
tag-message = ""

Take a moment to decide if you need any workspace- or crate-specific configuration ([package.metadata.release]) by reading the cargo-release reference.

Check that each crate has: name, description, version, authors, license, repository, documentation, readme.

Either defined in the crate TOML or in the workspace TOML + <field>.workspace = true

You must authenticate to crates.io to publish crates there:

# create account on https://crates.io
# create API token on the website
cargo login THE_API_TOKEN
# or `CARGO_REGISTRY_TOKEN` for CI

After that, it's all about defining what kind of release you want to do each time:

# dry run for a release candidate (rc) e.g. 1.0.0 -> 1.0.1-rc.1
cargo release rc
# publish a release candidate
cargo release rc --execute
# now you could go to crates.io or try "=1.0.1-rc.1" version in your projects

# publish the current pre-release as a full release e.g. 1.0.1-rc.1 -> 1.0.1
cargo release release --execute


# or, if you want to do a release without a pre-releases
cargo release major|minor|patch --execute

These commands will

  1. edit versions in TOML(s)
  2. (optional) search and replace version text in other files
  3. create a new git commit
  4. git tag the commit
  5. publish the crates to the registry
  6. push the commit and tag to the git repository

The command also supports cargo release <STEP> where you can do this process step by step or do additional steps.

Read the cargo-release reference for more details.