crate-upgrade

# 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.