Treat a major framework upgrade as a roadmap item with its own scope, not a background task. Inventory what uses the framework, read the breaking changes, split the work into stages you can ship, and set a deadline tied to the end of security support rather than to a convenient quarter.
Why a major version is different
Under Semantic Versioning, a major version number signals incompatible API changes. A minor or patch release is meant to be backward compatible. So a major bump is the point where your code is allowed to break, and where the work is not automatic.
Waiting has a price. Once the old major line stops receiving security fixes, any new vulnerability in it stays open in your product. Check the framework's published support policy for the date, because it differs per project.
Steps
- Find the deadline. Look up the end of security support for your current major version in the project's own documentation. Work backwards from it.
- Inventory. List every service and package that depends on the framework, including plugins and internal libraries. A dependency inventory makes this faster.
- Read the breaking changes. Use the project's migration guide and release notes. Group changes by effort: mechanical, needs tests, needs redesign.
- Stage it. Prefer small releases: first move to the latest release of the current major, then clear deprecation warnings, then cross the major boundary.
- Gate each stage. Run tests and a scan on each release candidate so new findings are caught early.
- Plan rollback. Know how you will revert, and which data changes cannot be reverted.
Estimating the effort
| Input | Question |
|---|---|
| Surface area | How many modules touch the framework? |
| Test coverage | Will tests tell us when something breaks? |
| Plugins | Do all our plugins support the new major? |
| Team knowledge | Has anyone done this upgrade before? |
Low coverage is the main reason upgrades slip. If tests are thin, add a stage that writes them before the upgrade starts.
Communicate to stakeholders
Frame the upgrade for the roadmap in terms they can weigh: a date after which new vulnerabilities in the old version go unpatched by the upstream project, and the engineering weeks needed to avoid that. Do not promise a ship date until the inventory and breaking change review are done.
Try it yourself
Click through it at your own pace, or open it full screen.
Notice how the demo separates findings that have a fix available from those that do not. A framework upgrade often clears a whole group at once.
Quick check
Can we skip the intermediate releases?
You can, but it makes failures harder to diagnose. Staged upgrades are slower on paper and faster in practice.
Who sets the deadline?
The end of upstream security support sets the outer limit. The team and product manager choose the earlier date.
Safeguard's dependency scanning and policy gates can flag end of life frameworks and block releases that use them, and the free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
