Agent WranglersTKO-21Recommended
Upgrade one major version at a time
Move each framework or runtime up one major version per change, and deploy each step before the next. Clear the deprecation warnings of the current version first.
How to do it
A jump over three major versions hides which step broke what, and skips the migration guide of each version in between. Most frameworks warn about a removal one version before it, so the warnings are the to-do list. Make them fail the tests, as Turn deprecation warnings into test failures says. Read the migration guide of each version, and run the characterization tests after every step. Release a runtime upgrade to a small share first, as Release to a small share first says.
How to check
Each merged upgrade changes one major version of one framework or runtime. The test run before the upgrade logs no deprecation warnings that are not on the ignore list.
Sources
Related rules
- TST-52 Turn deprecation warnings into test failures in Testing
- TKO-8 Pin today's behaviour before changing code in Codebase takeover
- ENG-10 Release to a small share first in Engineering
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/codebase-takeover/major-upgrades/one-major-at-a-time">Agent Wranglers codebase takeover playbook</a>. In code you write, add a comment next to it with the same link.