Framework Upgrader

Framework Upgrader

Treat a major-version framework upgrade as a sequence of small, mergeable, reversible PRs against a green main, driven by the framework's official migration path. A single long-lived upgrade branch is the failure mode.

Workflow

1. Diff the changelog into a concrete edit list. Open the framework's own upgrade guide (React upgrade guide, Rails rails app:update, Spring Boot migration notes, Angular ng update). Grep your codebase for the removed/renamed APIs, deprecated config keys, and changed defaults the guide names. Produce a checklist of specific edits with file locations - never a vague "upgrade React." Split each item into required-now vs. deferrable-deprecation.
2. Get green on the current major first. Confirm the suite passes and clear every deprecation warning on the current version in their own PRs, since most frameworks promote those warnings to errors in the next major. This is the highest-leverage prep step: it shrinks the actual jump to near zero. Never skip an intermediate major - walk one major at a time (4→5→6, not 4→6), because guides and codemods assume single-step jumps.
3. Run the official codemods per area, in isolated commits. Apply the provided transforms (react-codemod / npx codemod, Angular ng update schematics, OpenRewrite recipes). One area per commit so each diff is reviewable. Write custom jscodeshift/AST transforms for repeated project-specific patterns the official codemods miss.
4. Review every hunk; codemods are not authoritative. Read each generated change. Codemods skip dynamic/indirect usages and occasionally rewrite incorrectly. Hand-fix what they missed before the PR lands.
5. Run old and new side by side where the toolchain allows. Use the framework's coexistence path (React gradual adoption, Rails dual-boot with a second Gemfile, Angular compatibility modes). Land prep and codemod PRs to main continuously; keep each independently revertible and CI-gated. Keep hand-written diffs under roughly 400 changed lines per PR; uniform mechanical codemod output can run larger, but flag it as machine-generated so reviewers spot-check instead of line-reading.
6. Verify beyond compilation. Run the full suite, smoke-test critical flows, and check bundle size and startup time - treat a regression beyond ~5% on either as a stop-and-investigate signal. Watch error rates on a canary for at least 24 hours (one full traffic cycle) before rolling wide. New majors change defaults (rendering, serialization, timezone, strictness) that pass type checks but alter behavior - diff observable output where you can.
7. Stop and re-scope a blocked dependency. If a dependency has no version compatible with the target and no maintained fork, pause. You are now also migrating off that library, which is a separate project - flag it, scope it, and sequence it on its own.