Dependency Upgrades skill for Codex

An upgrade is done when the lockfile changed only for the packages you meant to move, every breaking change listed in their release notes was checked against this codebase, the full verification suite passes, no new deprecation warnings appeared, and each major bump sits in its own commit so it can be reverted alone.

Inspect first

1. Read AGENTS.md for the package manager, supported runtime versions and the verification commands. Identify the manager from the lockfile, never by guessing: package-lock.json (npm), pnpm-lock.yaml, yarn.lock, uv.lock, poetry.lock, requirements*.txt, go.sum, Cargo.lock, Gemfile.lock, gradle/libs.versions.toml.
2. Confirm a green baseline: run the full suite, type check and build before changing anything, and save the warning output for comparison later.
3. Network: listing outdated packages, reading release notes and installing all need network access, which the Codex sandbox may block. Ask for approval or for the user to run the install step if it is denied. Never work around the sandbox.

Inventory

npm outdated                      # or: pnpm outdated; avoid interactive pickers that need a TTY
uv tree --outdated --depth 1      # uv projects
pip list --outdated               # plain pip environments
poetry show --outdated --top-level
go list -m -u all | grep '\['     # modules with an available update
bundle outdated --only-explicit
./mvnw versions:display-dependency-updates     # Maven with versions plugin

Classify each candidate:

Class	Examples	How to move
Patch / minor, low risk	utility libs, type packages	Batch into one commit per area, after reading notes for anything security-related
Major, isolated	a date library, a CLI parser	One package per commit
Major, ecosystem	React + react-dom + @types/react; Next.js + eslint-config-next; Spring Boot BOM	Move the group together in one commit
Runtime	Node, Python, Go, JDK version	Separate change: CI matrix, Docker images, engines, .nvmrc, requires-python, go directive
Transitive only	a vulnerable sub-dependency	Update the parent first; override only as a last resort

Ask the user which majors are in scope if more than a couple are outstanding. A PR that moves six majors at once cannot be reviewed or bisected.

Read before you bump

For every major (and any minor of a framework), find the release notes and migration guide. Sources, in order of reliability:

1. The project’s migration guide or UPGRADING document.
2. GitHub releases: gh release list -R owner/repo and gh release view <tag> -R owner/repo.
3. CHANGELOG.md in the repo, or inside the installed package after install (node_modules/<pkg>/CHANGELOG.md), which also works offline.

Turn each listed breaking change into a search against this codebase:

rg -n "moment\(|\.isSameOrAfter\(" src/          # removed or renamed APIs
rg -n "from 'lib/legacy'|require\('lib/legacy'\)" # removed entry points
npm view <pkg>@<new> peerDependencies engines    # peer and runtime constraints

Record the results as a checklist; it becomes the PR description’s risk section.

Upgrade procedure

For each major, in order:

• Move to the latest minor of the current major first, run the suite, and fix every deprecation warning. Deprecations in the last minor usually are the next major’s removals.
• Bump to the new major with an exact command, not by hand-editing the lockfile:

npm install date-fns@^4
pnpm add date-fns@^4
uv add 'pydantic>=2.9,<3' && uv lock
poetry add 'pydantic@^2.9'
go get github.com/jackc/pgx/v5@latest    # Go majors change the import path: update imports too
cargo update -p serde --precise 1.0.210  # within the semver range in Cargo.toml
bundle update --conservative rails

• Run the official codemod if the project ships one (for example npx @next/codemod, npx ng update @angular/core @angular/cli, npx @tailwindcss/upgrade), then read its diff; codemods miss dynamic cases.
• Apply the remaining changes from your breaking-change checklist.
• Verify (next section). Commit with the package, from and to versions, and the notable migration work in the body.

For patch/minor batches: update, verify, commit. If something breaks, bisect the batch by halves rather than reading every changelog.

Verify each step

<test command from AGENTS.md>
npx tsc --noEmit            # types catch most removed APIs in TS projects
npm run build               # bundlers surface ESM/CJS and export-map changes
python -W error::DeprecationWarning -m pytest -q   # promote new deprecations to failures
NODE_OPTIONS=--throw-deprecation npx vitest run     # Node deprecations become errors
go build ./... && go vet ./... && go test ./...

Also check:

• The lockfile diff touches only the intended packages and their transitive deps: git diff --stat -- '*.lock' package-lock.json pnpm-lock.yaml. Large unrelated churn means the lockfile was regenerated; redo the step.
• Bundle size or binary size if the project tracks it.
• A runtime smoke test of the main entry point (start the server, hit one route, run the CLI once). Many breaks only show at runtime: config schema changes, plugin loading, ESM-only packages.

Overrides and pins

Overrides (overrides in npm, pnpm.overrides or overrides in pnpm-workspace.yaml, resolutions in Yarn, override-dependencies under [tool.uv]) force a transitive version and can break the parent package. Use one only when the parent has no fixed release, add a comment with the reason and the condition for removing it, and test the parent’s code path specifically.

Pinning to an exact version because the next one broke something is acceptable as a documented, temporary decision; say what must happen to unpin.

Hard rules

• Never delete and regenerate the whole lockfile to “fix” a conflict or error; it silently upgrades everything.
• Never bump a major without reading its breaking changes against the codebase.
• Never use --force or --legacy-peer-deps to silence peer conflicts without telling the user which peer is unsatisfied and why it is safe.
• Do not mix upgrades with feature work or refactors in the same commit.
• Security-driven upgrades still follow this process; triage of advisories themselves belongs to dependency-scanning.

Report

### Dependency upgrades
| Package | From | To | Commit | Notes |
|---|---|---|---|---|
| date-fns | 2.30.0 | 4.1.0 | a1b2c3d | ESM-only; 3 imports changed; `format` tokens unchanged |
| minor/patch batch (14 pkgs) | | | d4e5f6a | no code changes |
Deferred: eslint 8 -> 9 (flat config migration; separate PR, see eslint-setup)
Verification: tests 512 passed, tsc clean, build OK, no new deprecation warnings
Overrides added: none