rust-semver

Rust Semver and Release Workflow

Authority: Cargo Semver Reference, RFC 1105 (Semver), cargo-semver-checks, RustSec Advisory Database.

This skill owns what is and isn't a breaking change in Rust, the publishing workflow for crates.io, and workspace-wide release coordination. It does not own API design (rust-api-design), Cargo manifest mechanics (rust-cargo-build), or lint config (rust-style-clippy).

Capability Boundaries

✅ Strengths

1. Determining whether a specific code change is a major, minor, or patch bump
2. Understanding pre-1.0 (0.x.y) special rules
3. Running and interpreting cargo-semver-checks (270+ lints)
4. Coordinating multi-crate workspace releases via cargo-workspaces
5. Handling yank, deprecate, and RustSec advisory workflows
6. Knowing the semver implications of #[non_exhaustive], sealed traits, feature flags, hidden modules
7. Writing release notes that match the change type

⚠️ Prerequisites

1. A Rust crate with a clear public API surface — see rust-api-design
2. Cargo manifest and cargo publish basics — see rust-cargo-build

❌ Out of Scope

1. Designing the API itself → rust-api-design
2. Cargo manifest format and build configuration → rust-cargo-build
3. Clippy lint rules → rust-style-clippy
4. Test design for verifying behavior → rust-testing

Data Privacy

This skill does not collect, store, or transmit user data. Publishing to crates.io is a public action — confirm with the user before running cargo publish.

Part 1: What Is the Public API?

Semver applies to public API surface. In Rust, the public API is everything visible to downstream — but the definition is subtle.

Visible items

// src/lib.rs
pub fn hello() {}                    // public API
pub struct User { pub name: String } // public API
pub mod network {                    // public API
    pub fn connect() {}              // public API
}

mod internal {                       // private — NOT public API
    pub fn helper() {}               // pub, but module is private → not reachable
}

Rule: an item is public API if and only if a downstream crate can name it without `unsafe`. A pub item inside a pub(crate) module is not public API.

Reachability through re-exports

// src/lib.rs
mod hidden;
pub use hidden::Config;   // Config IS public API (reachable via crate root)

Even though hidden is private, Config is reachable via the re-export — it's public API.

Hidden modules

#[doc(hidden)]
pub mod unstable { /* */ }

`#[doc(hidden)]` does NOT remove items from the public API for semver purposes. Downstream can still use crate::unstable::Foo. If you intend them to be unstable, gate behind a feature flag or move to a private module.

Feature-gated items

#[cfg(feature = "json")]
pub mod json;   // public API only when feature enabled

The semver contract is per feature combination. Adding items under json is a minor bump for users with json enabled, and invisible to users without.

Part 2: Breaking vs Non-Breaking Changes

The Cargo Book lists the canonical changes. Summary:

Always breaking (major bump, except pre-1.0)

Non-breaking (minor or patch bump)

Subtle cases

Adding a method to a public trait

// Before
pub trait Foo { fn a(&self); }
// After
pub trait Foo { fn a(&self); fn b(&self); }   // ❌ BREAKING

Downstream impls of Foo will fail to compile (missing b). Fix: either (a) bump major, (b) seal the trait before adding methods, or (c) add b as a default method (fn b(&self) {}).

Adding a default method to an unsealed trait

pub trait Foo { fn a(&self); fn b(&self) {} }  // ✅ non-breaking

Default methods are non-breaking. But you cannot later remove the default without breaking.

Generic param with default

// Before
pub fn parse<T>(input: &str) -> T { /* */ }
// After
pub fn parse<T = String>(input: &str) -> T { /* */ }   // ✅ non-breaking

Adding a default to a generic is non-breaking. Removing the default IS breaking.

Trait object safety

If Foo is currently object-safe (Box<dyn Foo> works), making it object-unsafe (adding Self: Sized bound, adding generic method) is breaking.

Lifetime additions

// Before
pub fn parse(input: &str) -> &str { /* */ }
// After
pub fn parse<'a>(input: &'a str) -> &'a str { /* */ }   // ✅ usually non-breaking

Lifetime elision makes most lifetime changes transparent.

Part 3: Pre-1.0 (0.x.y) Rules

Crates at version 0.x follow modified semver:

So 0.1.0 → 0.2.0 is a major bump. 0.1.0 → 0.1.1 is a patch (bug fix).

# Allowed in Cargo.toml:
[dependencies]
my-crate = "0.1"     # means >=0.1.0, <0.2.0

Once you hit 1.0.0, normal semver resumes.

When to go 1.0

• API is stable (no planned breaking changes for ~6 months)
• Used by other crates (signal of usefulness)
• All fundamental design decisions are settled

Don't fear 1.0. Many crates live too long at 0.x because they're afraid of the commitment. The cost of 1.0 is "I commit to breaking changes requiring major bumps," which is usually fine.

Part 4: cargo-semver-checks

`cargo-semver-checks` is a tool that compares your crate's current public API against a published version and flags breaking changes. 270+ lints cover most cases.

Install and run

cargo install cargo-semver-checks --locked

# Before publishing a new version:
cargo semver-checks check-release

# Compare against a specific baseline:
cargo semver-checks check-release --baseline-version 1.2.0

# Compare against a git tag:
cargo semver-checks check-release --baseline-tag v1.2.0

Output interpretation

--- failure function_missing ---
Description: Function removed or renamed, or return type changed.
Error: the function `parse` was removed from the API

Each failure is a semver violation. Fix by either:

1. Restore the item (don't actually remove it)
2. Bump the major version (acknowledge the breaking change)
3. Use a compatibility shim (re-add under the old name, delegating to new)

CI integration

# .github/workflows/semver.yml
name: Semver Check
on: [pull_request]
jobs:
  semver:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: obi1kenobi/cargo-semver-checks-action@v2

PRs that introduce breaking changes will fail CI unless the version is bumped accordingly.

Common lint hits

Part 5: Publishing Workflow

Single-crate publish

# 1. Bump version in Cargo.toml
# 2. Update CHANGELOG.md
# 3. Run quality gates
cargo fmt --all --check
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo semver-checks check-release

# 4. Verify package contents
cargo package --list    # show files included
cargo package           # build the .crate in target/package/
cargo publish --dry-run # full simulation

# 5. Publish
cargo publish           # 🚨 public action — confirm with user first

Workspace lockstep publish via cargo-workspaces

For multi-crate workspaces, `cargo-workspaces` automates the version bump + publish dance:

cargo install cargo-workspaces

# Bump all members together:
cargo workspaces version minor      # 0.1.0 → 0.2.0 across all members

# Bump with custom prerelease:
cargo workspaces version prerelease --pre-id beta

# Publish all members in topological order:
cargo workspaces publish

cargo-workspaces:

1. Edits each member's Cargo.toml version
2. Updates internal path = "" dependencies to the new version
3. Commits + tags if you pass --no-individual-tags or --individual-tags
4. Publishes in dependency order (deps before dependents)

Yank a published version

If a version has a critical bug, yank it (prevents new dependencies on it, doesn't remove existing):

cargo yank --vers 1.2.3
# To undo:
cargo yank --vers 1.2.3 --undo

Yanked versions remain in the registry for projects with Cargo.lock pinning them.

Deprecate a crate

Mark the crate as deprecated on crates.io via the maintainer's page. Downstream will see a deprecation notice when they run cargo add.

Part 6: RustSec Advisories

RustSec Advisory Database tracks known vulnerabilities in published crates.

cargo-audit

cargo install cargo-audit --locked
cargo audit               # scan Cargo.lock against advisory DB
cargo audit --deny warnings   # fail CI on any advisory

cargo-deny (more comprehensive)

`cargo-deny` covers:

• advisories — RustSec
• licenses — deny unauthorized licenses
• bans — deny specific crates
• sources — deny specific git/registry sources

# deny.toml
[advisories]
db-urls = ["https://github.com/rustsec/advisory-db"]
yanked = "deny"

[licenses]
allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]
confidence-threshold = 0.8

cargo install cargo-deny --locked
cargo deny check

Responding to an advisory in your crate

1. Acknowledge in the issue tracker
2. Patch and publish a new version
3. File an advisory with RustSec (if applicable): https://github.com/rustsec/advisory-db/
4. Yank the vulnerable version (after the fix is published)
5. Communicate to users via CHANGELOG + release notes

Part 7: Release Notes

For every publish, write a CHANGELOG.md entry. Suggested format:

## [1.2.0] - 2026-07-21

### Added
- `Client::builder()` for ergonomic construction (#45)
- `Visibility::IncludeHidden` variant

### Changed
- `parse()` now accepts `impl AsRef<str>` instead of `&str`

### Deprecated
- `Client::new()` — use `Client::builder()` instead

### Fixed
- Panic on empty input in `parse()` — now returns `Err`

Tools:

• `cargo-release` — automates version bump + tag + publish
• `release-plz` — generates CHANGELOG from conventional commits
• setuptools-changelog — manual

Workflow

1. Inventory the diff — what changed in pub items since the last release?
2. Classify each change — breaking, additive, or fix (see Part 2)
3. Decide version bump — major/minor/patch; remember pre-1.0 rules
4. Run cargo-semver-checks — confirm your classification matches the tool
5. Update CHANGELOG — what changed, why, with migration notes
6. Run quality gates — fmt, test, clippy, doc
7. Publish — single (cargo publish) or workspace (cargo workspaces publish)
8. Handle post-publish — yank if broken, file advisory if security

Decision Shortcuts

Resources

• Semver Reference (full) — full change catalog
• cargo-semver-checks Lint Catalog
• Workspace Publishing Cookbook — cargo-workspaces recipes
• examples/golden-semver/ — a crate demonstrating a non-breaking version bump

Upstream Sources

• Cargo Semver Reference
• Cargo Publishing Guide
• RFC 1105 — API Evolution
• cargo-semver-checks
• cargo-workspaces
• cargo-release
• release-plz
• RustSec Advisory Database