---
title: "Upgrade one major version at a time · Agent Wranglers"
url: https://agentwranglers.se/playbook/codebase-takeover/major-upgrades/one-major-at-a-time
id: TKO-21
level: Recommended
updated: 2026-10-22
tokens: 742
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Upgrade one major version at a time

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Major upgrades](https://agentwranglers.se/playbook/codebase-takeover/major-upgrades.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: TKO-21
- Level: Recommended
- Chapter: [Major upgrades](https://agentwranglers.se/playbook/codebase-takeover/major-upgrades.md)
- Rule: 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.
- 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.
- How: 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](https://agentwranglers.se/playbook/testing/test-quality/deprecations-fail-tests.md) says. Read the migration guide of each version, and run the [characterization tests](https://agentwranglers.se/playbook/codebase-takeover/characterization-tests/pin-behaviour-first.md) after every step. Release a runtime upgrade to a small share first, as [Release to a small share first](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/staged-rollouts.md) says.

## Sources

- [Django on upgrading to a newer version](https://docs.djangoproject.com/en/stable/howto/upgrade-version/)

## Related rules

- TST-52 [Turn deprecation warnings into test failures](https://agentwranglers.se/playbook/testing/test-quality/deprecations-fail-tests.md) in Testing
- TKO-8 [Pin today's behaviour before changing code](https://agentwranglers.se/playbook/codebase-takeover/characterization-tests/pin-behaviour-first.md) in Codebase takeover
- ENG-10 [Release to a small share first](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/staged-rollouts.md) in Engineering

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Keep one list of support end dates](https://agentwranglers.se/playbook/codebase-takeover/major-upgrades/support-end-dates.md)
- Next: [Run codemods in their own commit](https://agentwranglers.se/playbook/codebase-takeover/major-upgrades/codemods-first.md)
- [Major upgrades](https://agentwranglers.se/playbook/codebase-takeover/major-upgrades.md)