Release & Versioning

Rust uses SemVer in Cargo.toml. Applications tag git releases; libraries publish to crates.io with changelog entries and API stability promises.

Recipe

# Install release helper
cargo install cargo-release
 
# Bump patch version, update lock, tag
cargo release patch --execute

# Cargo.toml
[package]
name = "my-lib"
version = "0.3.2"
rust-version = "1.97"

When to reach for this:

• Publishing workspace crates
• Shipping CLI tools with --version output
• Coordinating breaking API changes across dependents

Working Example

# Binary service: git tag drives deploy
git tag v2.1.0
git push origin v2.1.0
# CI builds container ghcr.io/acme/api:2.1.0

// Expose version in CLI
const VERSION: &str = env!("CARGO_PKG_VERSION");
 
fn main() {
    println!("my-cli {VERSION}");
}

What this demonstrates:

• CARGO_PKG_VERSION embeds compile-time version
• Git tags align with container tags
• cargo-release automates manifest + git tag

Deep Dive

SemVer Rules for Rust APIs

#[non_exhaustive] and sealed traits soften evolution for libraries.

Changelogs

Maintain CHANGELOG.md with Keep a Changelog format. Link sections to GitHub compare URLs.

Workspace Releases

Release internal crates in dependency order or use release-plz for coordinated bumps.

Gotchas

• Breaking change in patch - downstream breakage. Fix: CI with cargo semver-checks.
• Forgot to publish all workspace members - version skew. Fix: release checklist per crate.
• 0.x crate treated as stable - SemVer allows breaks on minor. Fix: document stability policy.
• Git tag without lockfile update - non-reproducible tag builds. Fix: commit lock with tag.
• Yanked crate left in lock - cargo build fails. Fix: cargo update -p crate promptly.

Alternatives

FAQs

Related

• Publishing to crates.io
• CI/CD for Rust
• Crate Publishing Skill
• Release management

External Related Links

• The Cargo Book - Official guide and reference for Cargo.
• crates.io - Official crate registry.
• docs.rs - Automatic documentation hosting for every crate on crates.io.
• Programming Rust: Fast, Safe Systems Development (Amazon) - Blandy, Orendorff, Tindall.
• The Rust Programming Language, 2nd Edition (Amazon) - Steve Klabnik & Carol Nichols.

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.