Upgrade

Upgrading is a process: impact assessment, staged rollout, rollback plan, and verification.

The goal is to reduce risk and keep shipping. A small, verified upgrade every week beats a big, scary upgrade every year.

A staged plan

Think of upgrades as a pipeline: you want early signals and easy rollback. That requires staging and separation of concerns.

• Inventory: libraries, runtime, build chain, deployment.
• Upgrade in small steps and ship often.
• Verify with a tight checklist and metrics.

Preflight: inventory and risk classification

Before touching versions, map impact. Most upgrade pain comes from hidden coupling and unknown blast radius.

• Dependency graph: identify the “root” deps that many packages rely on (React, router, build tool).
• Runtime vs tooling: separate changes that affect production behavior from developer tooling.
• Risk tiers: classify modules into high/medium/low risk by traffic and criticality.

A practical staged rollout

A reliable ordering is: tooling → runtime → behavior. Each step changes a different failure mode, so isolating them keeps debugging cheap.

1. Tooling + types: `TypeScript`, `ESLint`, build config. Make `CI` green first.
2. Runtime deps: upgrade core runtime libraries in small jumps, one root dependency at a time.
3. Behavior changes: fix deprecations and breaking behaviors with targeted migrations.
4. Hardening: performance checks, accessibility regression checks, and security scanning.

Verification matrix

Define what must pass before shipping. Tight feedback loops reduce risk more than heroic late-night debugging.

Your matrix should be small but strict. If a signal is noisy, either fix it or remove it—noise trains teams to ignore red builds.

Rollback and blast radius

A rollback plan is not pessimism; it is engineering maturity. The fastest incident is the one you can revert in minutes.

• Keep changes reversible: avoid mixing migrations that cannot be separated.
• Roll out gradually (canary, percentage rollout) for high-risk changes.
• Have a clear revert procedure and who is on call for the window.

Release checklist (copyable)

Copy this into your release PR. The point is not paperwork—it’s making sure you do the same high-signal checks every time.

- [ ] CI green: lint / typecheck / build
- [ ] Smoke: critical pages load; critical actions work
- [ ] Error paths: loading/error/empty states checked
- [ ] Observability: logs/metrics/alerts ready
- [ ] Rollback: revert steps documented and tested
- [ ] Communication: release notes and known issues

Further reading

• Guides: Testing
• Guides: Security