dependency-and-framework-upgrade

name	dependency-and-framework-upgrade
description	Upgrade a stuck dependency, framework, or language version incrementally — one major at a time, on green tests, deprecations resolved between each — instead of a single risky leap. Reach for this when a system is several versions behind.

Skill: Dependency & framework upgrade

A system three majors behind doesn't jump three majors at once.

Step 1 — Establish the safety net

Ensure characterization/regression tests cover the surface that the upgrade touches (use characterization-testing). No green baseline → build one first.

Step 2 — Map the upgrade path

Read each major version's migration guide and breaking-change/deprecation list between your current and target versions. The path is a sequence, not a destination.

Step 3 — Upgrade one major at a time

Bump a single major version, resolve its deprecations and breaks, get tests green, commit. Then the next. Never batch majors — a failure becomes un-bisectable.

Step 4 — Separate the upgrade from refactors

The version bump is its own change; resist "while I'm in here" refactors in the same commit (§2 #3).

Step 5 — Verify and pin

Run the full suite and a smoke test of the real app, then pin the new versions. Record the path taken so the next upgrade starts from a known state.

Re-verify version-specific facts at use — see the dated ../../knowledge/legacy-modernization-2026-capability-map.md. DDL/schema changes inside the upgrade route to database-engineering.