migrate-dependency

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

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.

More agent context in luminik-io/alfred

13 other files this repository gives its agents.