AGENTS.md — Framework upgrades

Upgrade a framework or major dependency in planned, reversible steps with tests at each one, so you stay current without a long, risky freeze.

How to do it

1. Read the migration notes — Read the official release notes and migration guide for every major version between current and target. List each breaking change that touches your code, with the files affected.
2. Get to a clean baseline — Upgrade to the latest minor of your current major first, fix every deprecation warning, and confirm the full test suite and build are green.
3. Check the dependency tree — List plugins and libraries that depend on the framework and confirm each has a release supporting the target version. Note blockers and their workarounds.
4. Run official codemods — Apply the codemods or automated migration tools the framework provides, one at a time, committing after each with its name in the message.
5. Fix what remains by hand — Work through remaining breaking changes in small commits, running tests after each. Do not mix in unrelated refactors or features.
6. Verify beyond unit tests — Run end-to-end journeys, compare bundle size and performance against the baseline, and check logs on a preview environment for new warnings.
7. Release with a rollback path — Ship behind a staged rollout or to a canary first. Keep the previous lockfile and build artifact so you can redeploy the old version in minutes.
8. Clean up — Remove compatibility shims and temporary flags, update the documented versions, and note the upgrade in the changelog.

Checklist (before a pull request)

• Every breaking change from the migration guide is listed and resolved or marked not applicable
• No deprecation warnings remain in build or test output
• All direct dependencies support the new version
• Unit, integration and end-to-end suites pass
• Bundle size and key performance metrics are within budget versus the baseline
• A tested rollback path exists
• Lockfile, documented versions and changelog are updated

Rules

• Move one major version at a time. (Skipping majors stacks breaking changes and hides which one caused a failure.)
• Keep the upgrade in its own pull request series with no feature work. (Mixed changes make regressions impossible to attribute.)
• Run the dependency audit after the upgrade and fix new high or critical findings before release. (Upgrades pull in new transitive packages with their own issues.)
• Compare bundle size, build time and runtime metrics before and after. (Major versions often change defaults that affect speed.)
• Watch error rates closely for the first day after release and roll back on a clear rise. (Some breaking changes only show with real traffic.)

Checks

Generated from the Celestial engineering practice “Framework upgrades”.