rust-release

Rust Release Engineering

Workflow for versioning, publishing, and distributing Rust crates and binaries. Local release preparation and dry-runs are autonomous. Tagging, pushing, publishing, uploading, or production deployment requires explicit user authorization for that operation.

When to Use

• Publishing a library crate to crates.io
• Setting up automated release pipelines
• Distributing compiled binaries (CLI tools, services)
• Managing changelogs and SemVer bumps
• Cross-compiling for multiple targets

Library Crate Release

Tools

Tool	Purpose
release-plz	Automated PR with version bump, changelog, and publish
cargo-release	Manual release with validation, tagging, and push
cargo-semver-checks	Detect accidental breaking changes

Process

1. Ensure Cargo.toml has complete metadata: description, license, repository, keywords, categories, rust-version.
2. Run cargo semver-checks to detect unintentional breaking changes.
3. Update version following SemVer:
   • MAJOR: breaking public API changes
   • MINOR: new public functionality, backward-compatible
   • PATCH: bug fixes only
4. Update CHANGELOG.md (or let release-plz generate it).
5. Run full CI (fmt, clippy, test, doc).
6. Tag the release: vX.Y.Z.
7. Publish: cargo publish --dry-run then cargo publish.

release-plz Automation

# .github/workflows/release.yml
name: release

on:
  push:
    branches: [main]

jobs:
  release-plz:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: dtolnay/rust-toolchain@stable
      - uses: MarcoIeni/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

cargo yank

• Removes a version from the index for new resolves
• Does NOT delete the published artifact
• Use for broken versions, not for "un-publishing"