Raw view: Safe dependency upgrade procedure
No invisible, zero-width, or bidi-control characters detected.
---
name: dependency-upgrade
description: Safe procedure for upgrading a dependency or a batch of dependencies - changelog and breaking-change review, lockfile regeneration, test and typecheck gates, and a rollback plan. Use when the user asks to bump, update, or upgrade a package, fix a Dependabot/Renovate PR, resolve a security advisory, or move to a new major version of a library or framework.
license: CC0-1.0
allowed-tools: Bash(npm *) Bash(pnpm *) Bash(yarn *) Bash(pip *) Bash(uv *) Bash(poetry *) Bash(cargo *) Bash(go *) Bash(git diff *) Bash(git stash *) Bash(gh release *)
metadata:
author: Waxmark
version: "1.0.0"
---
# Dependency Upgrade
Upgrades fail in two ways: silently (behavior changes no test catches) and loudly (build breaks). The procedure is ordered to surface the loud ones fast and to make the silent ones visible through changelogs.
## 1. Scope and baseline
- Confirm the package manager from the lockfile present: `package-lock.json` -> npm, `pnpm-lock.yaml` -> pnpm, `yarn.lock` -> yarn, `uv.lock`/`poetry.lock`/`requirements*.txt` -> uv/poetry/pip, `Cargo.lock` -> cargo, `go.sum` -> go.
- Record current and target versions. Classify the jump: patch, minor, or major. Majors get the full procedure; patches may skip step 2 if the changelog is a one-liner.
- Run the baseline before changing anything so failures can be attributed: `{{TEST_COMMAND}}` and the typecheck/lint command. Note the pass count.
- Ensure a clean tree (`git status --short` empty) or stash.
## 2. Read before you bump
For each package with a minor or major jump:
- Fetch the changelog/release notes: `gh release view <tag> --repo <owner>/<repo>`, or the `CHANGELOG.md` in the package's repo, or the registry page.
- Grep for: "BREAKING", "removed", "deprecated", "renamed", "default changed", "minimum Node/Python version", "peer dependency".
- Grep the codebase for every API named in those notes. List each hit as `file:line - what changes`.
- Check peer/transitive constraints: `npm ls <pkg>`, `pnpm why <pkg>`, `pip show <pkg>`, `cargo tree -i <crate>`.
Write the findings as a short table before touching the manifest. If the table has a row you cannot resolve, stop and ask.
## 3. Upgrade
One package (or one tightly coupled group, e.g. `react` + `react-dom`) per commit.
| Manager | Command |
|---|---|
| npm | `npm install <pkg>@<version>` |
| pnpm | `pnpm update <pkg>@<version>` |
| yarn | `yarn up <pkg>@<version>` |
| uv | `uv add <pkg>==<version>` / `uv lock --upgrade-package <pkg>` |
| poetry | `poetry add <pkg>@<version>` |
| pip | edit `requirements.in`, then `pip-compile` |
| cargo | `cargo update -p <crate> --precise <version>` |
| go | `go get <module>@<version> && go mod tidy` |
Let the tool regenerate the lockfile. Never hand-edit a lockfile. Review `git diff --stat` of the lockfile: an unexpected number of transitive changes means the range resolution did more than you asked.
## 4. Gate
Run in this order and stop at the first failure:
1. Install from lockfile in clean mode (`npm ci`, `pnpm install --frozen-lockfile`, `uv sync --locked`, `cargo build --locked`).
2. Typecheck / compile.
3. Lint (new deprecation warnings count as findings).
4. `{{TEST_COMMAND}}`. Compare the pass count to the baseline.
5. Apply the code changes from the step 2 table, re-run 2-4.
6. If the package has runtime behavior (ORM, HTTP client, framework), start the app or run the smoke script once.
## 5. Rollback plan
Before committing, write the rollback into the commit body so it survives the PR:
```
Rollback: git revert <sha>; <install command>. No data migration involved.
```
If the upgrade included a data or schema migration, the rollback must name the down-migration explicitly, or state that the change is forward-only.
## Output
```
## Upgrade: <pkg> <from> -> <to> (major)
Changelog findings: 3 (2 code changes, 1 N/A)
Code changes: src/db/client.ts:42, src/db/pool.ts:10
Gates: install ok | tsc ok | lint 0 new | tests 212/212 (baseline 212)
Lockfile: +4/-4 transitive
Rollback: git revert <sha>; pnpm install --frozen-lockfile
Not verified: production config uses TLS mode "require" - untested locally
```