Versioning Crates

Chester Wyke April 29, 2026 #Rust

Rust (Series)
Conditional Compilation
Install
Crate Serde
References
Cargo
Toolchain (Nightly)
String Formatting
Time
Crate Tokio
Publish Crate
rustfmt
Single file script
Snippets
CI
Pattern Type State
WASM
Create New Crate
Documentation
JSON
Pattern Builder
Testing
Working with collections of bytes
Thoughts about rust
Are we yet
OnceLock
Crate Actix Web
Stack Overflow
Crate Clap
Crate Poll Promise
Crate Insta
Tips
Create new egui project
Crate CSV
Crate egui
Iterators
Crate Tracing Subscriber
Regex
vscode
Enum Conversion
Macros
lettre
Google APIs
Versioning Crates

General tips

The cargo book has a great section on semver that gives examples different types of changes. Note: breaking changes require a bump of the first non-zero version number. That is what cargo looks for to determine incompatibility.
If you are releasing a library I highly recommend using cargo-semver-checks to help detect breaking changes. It’s not perfect but it’s always improving and is IMO a minimum amount of checking for libraries.

Opinions on when to bump version numbers

For clarity I’m not talking which part of the version number to bump here which indicates the type of changes included. I’m only taking about when that bump should happen.

Background

I’ve been giving this a lot of thought recently as I’ve noticed different ways that various crates do it. After much consideration I came up with my opinions below. I recently wanted to patch a library create that I depended on but they’d already bumped the version number in the git repo so I wasn’t able to use patch. Fortunately, it was a direct dependency so I just changed the source and was able to use my fork until my patch lands.

For library crates do not bump until you are ready to release. I think this is the best way because if someone needs to make a change to your crate having the version number the same as the released version makes it easy to use patch section of the Cargo.toml to replace your create throughout their dependencies. They are at least able to replace it without using patch if it’s a direct dependency, but would still be better IMO to use patch to separate out when you’re changing something on purpose.
For binary crates I think the bump should happen right after release by bumping the minor (or patch if still pre 1.0) and appending -dev. For example from 0.1.3 to 0.1.4-dev so that you users who build from the git repo instead have a different version number.