| name | migrate-dependency |
| description | Migrates a dependency to a target version by pinning it, reading the changelog for breaking changes, updating call sites, running the tests, and writing a migration note. Use when asked to "upgrade this dependency", "bump the version of X", "migrate to X v2", "update the library", or when a dependency is out of date, deprecated, or has a security advisory. Use before merging any dependency version bump. |
| license | MIT |
Migrate dependency
When to use
- A dependency is out of date, deprecated, or has a security advisory.
- You are asked to move from one major version of a library to the next.
- A transitive dependency needs pinning to a known-good version.
A version bump is a behavior change. Treat it like one: pin it deliberately,
find out what broke between versions, fix the call sites, and prove the tests
still pass. "Bumped and it built" is not done.
Procedure
- Pin the target version. Set the exact version you are migrating to in the
manifest (
package.json, pyproject.toml, build.gradle, etc.) and the
lockfile. Never migrate to a floating range; you cannot review what you
cannot name.
- Read the changelog and migration guide for every version between the
current and target. List the breaking changes that touch APIs this repo
actually uses. If the jump crosses several majors, note whether an
intermediate step is safer than one leap.
- Migrate the call sites. For each breaking change, update every usage:
renamed functions, changed signatures, removed options, new required
arguments. Search the repo for the old API to be sure none is missed
(
grep the old symbol). Do not paper over a removed API with a shim unless
the guide recommends one.
- Run the tests. Run the full suite, not just the touched module. A
dependency change can break a caller far from where you edited. If tests
assumed the old behavior, update the test to the new correct behavior (and
say why), do not weaken the assertion to make it pass.
- Write a migration note. Record what moved and why, so the next person
reading the diff understands the version jump.
Output
- The pinned manifest and lockfile change.
- The updated call sites, one edit per breaking change.
- The test result (full suite green; note any test updated to match new
behavior and why).
- A migration note: from-version to to-version, the breaking changes that
mattered, what was changed to accommodate them, and anything deferred to a
follow-up. Keep it in the PR body or a
CHANGELOG entry in the repo's voice.
