Upgrade debt compounds: why three majors behind is a project, not three tasks

Every team has one: the SDK that's three majors behind, with a ticket that keeps sliding to next sprint.

It's tempting to think of that as three upgrades' worth of work. It's usually more.

A real example: a senior engineer at Kore.ai let Versyka open security fixes on their code. It found 39 vulnerabilities across 3 pull requests, and two of the three were major version jumps, the kind that sit in a backlog because nobody has a free day. The one they merged would have taken about a day by hand.

Why it compounds

Guides assume the previous step. The v14 migration guide is written for someone on v13. If you're on v12, half of its "before" examples don't match your code, because v13 already changed them.

Changes stack. A method renamed in v13 is removed in v14. The v13 guide's recommended workaround is deprecated in v15. You end up researching history, not just the destination.

The ecosystem moves without you. Plugins, type packages and examples drop support for your version. Stack Overflow answers are for the new API.

Security fixes land on the latest major. At some point a vulnerability is fixed only in a version you can't reach without the whole migration. Now the upgrade is urgent and big at the same time.

A policy that keeps it small

1. Stay at most one major behind. Upgrade within a few weeks of a new major, after the first patch releases have landed.
2. Catch up one major at a time. v12 → v13, run the tests, merge. Then v13 → v14. Each step has one guide that matches your code.
3. Automate the boring part. Patch and minor bumps shouldn't need a human. Save attention for breaking changes.
4. Measure the gap. You can't manage what nobody can see.

For step 4, a quick script works:

npm outdated --long
pip list --outdated

or paste a package.json / requirements.txt into Versyka's free upgrade check, which shows how many majors behind each API SDK is and links its breaking changes.

And for step 3 and the breaking upgrades themselves, that's what Versyka is for.

How many majors behind is the oldest SDK in your codebase?