crate-upgrade

name

crate-upgrade

description

Use when upgrading a Rust crate / third-party dependency to a new version — especially non-trivial bumps where the new version removes previously-deprecated APIs, moves modules into separate crates, renames items, or otherwise has a broad blast radius across many crates. Covers reading the changelog, picking the version deliberately, splitting the migration into aspects, and migrating incrementally.

Upgrading a Rust crate dependency

Most version bumps are trivial: edit the version in Cargo.toml, mirror it in bazel/rust.MODULE.bazel, repin, build. This skill is for the non-trivial ones — where the new version removes APIs, splits modules into new crates, renames items, or the change ripples across many crates.

Work through the steps in order. Steps 3–6 are the ones that keep a large migration from turning into an unreviewable, half-broken mess.

1. Read the release notes first

Before touching any code, read the changelog for every version between the current and target version.

• Classify each change: deprecated vs removed, and in which version. Note module moves and module→separate-crate splits — those are easy to miss because they aren't "deprecations".
• Estimate the blast radius: grep the repo for the affected APIs (paths, macros, type names) to see how many crates/files are involved.

2. Pick the version deliberately — don't jump across a removal boundary

If the target version removes APIs that were only deprecated in an earlier version, do not bump straight to it in one leap.

• Prefer the highest version where the old and new APIs still coexist (typically the last version before the removal). Migrate the code to the new APIs there — while everything still compiles and the old APIs are merely deprecated — and only bump to the target version once the code no longer references anything that version removed.
• Example: if X was deprecated in 0.18 and removed in 0.20, do the migration on 0.19 first, then bump to 0.20.

3. For non-trivial migrations, list the aspects and get human sign-off

Most upgrades are straightforward and you can just do them. But when a migration spans several distinct aspects / areas — e.g. renamed accessor functions, a new inter-canister call API, a reject/error-type change, a module that became a separate crate — do not start coding.

• After reading the release notes and understanding the blast radius, enumerate the aspects, and for each note the API involved and the files/crates it touches.
• Present that split to a human and get it confirmed before starting.
• (A trivial single-aspect upgrade can skip this.)

4. Migrate one aspect at a time

• Do a single aspect across the codebase, and leave every other aspect on the existing (deprecated-but-working) API.
• Each step should compile and pass tests on its own — a small, self-contained, reviewable change.
• If an aspect's blast radius turns out far larger than expected (e.g. it hits production canisters or needs a brand-new dependency), that's a signal to stop and reassess the approach with a human, not to plow ahead.

5. Adopt the new names directly — no aliases or shims

Aim for the cleanest end state; the code should read as if it had always been written against the new API.

• When a symbol is renamed, update the call sites to the new name.
• Do not introduce use new::path::Thing as OldName aliases, wrapper functions, or other compatibility shims just to avoid touching call sites. They leave the codebase looking backwards instead of forward.

6. Don't abstract mid-migration

• Favor mechanical, localized edits, even when they produce boilerplate or duplication. Duplicating a small amount of code (e.g. a local type that preserves a Candid interface) is fine when it avoids re-architecting.
• Do not introduce new helpers/abstractions to smooth the migration while it is in flight.
• Only after the migration is fully done — it compiles, passes tests, and has been approved by a human — reassess whether the accumulated boilerplate/duplication is worth factoring out.

7. Keep Cargo and Bazel in sync

• Edit Cargo.toml first, then mirror the version in bazel/rust.MODULE.bazel (the crate.spec(...) for the crate). A new crate must be added to both.
• Repin the Bazel crate index: ./bin/bazel-pin.sh.
• Then follow the repo's standard Rust workflow: rustfmt → cargo check → cargo clippy → bazel build → bazel test (see the project CLAUDE.md).
• See the check-bazel-files skill after editing Bazel files, and run-in-dev-container for running builds/tests inside the dev container.