Dependency Upgrade Protocol

# Dependency Upgrade Protocol A dependency upgrade is a code change written by strangers. Read what changed before running anything, and upgrade in steps small enough to bisect. ## Step 0 — Inventory and triage 1. List outdated packages (`npm outdated`, `pip list --outdated`, `cargo outdated`, etc.) and any security advisories (`npm audit`, Dependabot alerts). 2. Triage into three buckets and handle them in this order: - **Security patches** — do first, separately, smallest possible scope. - **Patch/minor bumps** — batch is acceptable, but only within one ecosystem area at a time (e.g. all eslint plugins together, not eslint + the ORM). - **Major bumps** — one package per branch/PR. No exceptions. A PR with two majors and a regression is unbisectable. ## Step 1 — Read before you run For each package being bumped (mandatory for majors, skim for minors): - Read the changelog/release notes for *every version between current and target*, not just the target. Breaking changes hide in the minors you skipped. - Specifically hunt for: removed/renamed APIs you use (grep your codebase for each), changed defaults, new peer-dependency or engine requirements (Node/Python version), license changes. - Check the migration guide if one exists; majors with codemods (`npx @lib/codemod`) — plan to use them. - Note the release date. A major released last week has undiscovered bugs; unless you need it, let it bake or pin the previous major. ## Step 2 — Upgrade and review the lockfile - Bump the manifest explicitly to the intended version — avoid wildcard "update everything" commands, which hide unrelated transitive jumps. - **Read the lockfile diff.** It is part of the code review, not noise: - Expected package moved to the expected version? Any *other* top-level packages moved that you didn't ask for? - New transitive dependencies appearing — what are they, who pulls them in? A bump that adds 40 packages deserves a raised eyebrow and a look at the heaviest additions. - Integrity hashes changed for packages whose versions didn't — that's wrong; investigate. - Resolved URLs still point at your expected registry (catches registry/typosquat substitution). - Install with the lockfile-respecting command (`npm ci`, `pip-sync`, frozen lockfile) in a clean state, so what you test is what CI and prod will get. ## Step 3 — Verify in widening circles 1. Typecheck + lint + full unit/integration suite. Type errors after a bump are the cheap gift — fix them, they're the documented breakage. 2. Run the package's own surface deliberately: if you bumped the ORM, run the migration and a few real queries; HTTP client → exercise a request with retries/timeouts; build tool → compare production build output size and run the built artifact, not just the dev server. 3. Smoke test the app end to end: boot it, click through (or run e2e for) the two or three critical flows. Runtime behavior changes — changed defaults, stricter parsing — don't show up in unit tests with mocks. ## Step 4 — Land it bisectably - One commit per package (or tightly-related group), message naming old → new version and any code changes the bump forced: `chore(deps): zod 3.24 → 4.0; migrate .nonempty() to .min(1)`. - Code adaptations go in the *same* commit as the bump that requires them — a commit where the suite fails until the next one breaks bisect. - In the PR description: link the changelog, list the breaking changes that applied to you, state what you smoke-tested. - After deploy, watch error rates for the affected paths; know the revert is a one-commit revert because you kept it atomic.