Estimating a framework upgrade

How to estimate a framework upgrade: why a major version bump is a project, not a ticket, and how to break it into stories you can actually size.

Major version upgrades aren’t tickets. They’re projects.

Patch versions are tickets. Minor versions are usually tickets. Major versions — the ones with breaking changes, deprecation cycles, peer-dependency cascades, and “we recommend migrating to…” in the changelog — are projects, and planning poker isn’t the right tool for sizing them whole. The story that says “upgrade to React 19” or “Postgres 16” is not the work; it’s the wrapper around the work.

Treating the upgrade as a single estimate produces a single failure mode: the team votes 13, runs out of time in week three, and ships a half-migrated codebase that has the new framework’s bugs and the old framework’s idioms. The honest move is to break the upgrade into a sequence of smaller stories, each independently estimable, with the upgrade itself as the umbrella project.

What gets said in the room

Engineer: “The codemod handles most of it.”

Lead: “Most of what? What does it not handle?”

SRE: “Do all our deps support the new version yet?”

QA: “What’s our regression-testing strategy for the diff?”

PM: “Are we shipping anything else this sprint, or is this the sprint?”

Questions worth asking before voting

  • How many breaking changes apply to our codebase — read the changelog, count?
  • Do peer dependencies support the target version, or do we cascade?
  • Codemod or manual? What’s the codemod’s coverage?
  • Test coverage on the changed surfaces — adequate, or do we add tests first?
  • Rollback strategy if it goes badly mid-sprint?
  • One PR or many? If many, what’s the dependency order?

The right output of this conversation is often “this isn’t a story, it’s a project — let’s plan it that way,” then split it into slices the team can each estimate against a reference story.

Don’t put a single number on a major upgrade. Break it into stories, then size those.

See estimation techniques for fuzzier or larger work, and estimating a research spike for the investigation that should precede the estimate. Browse the other worked estimation examples.