Every engineering organization carrying a mature mobile codebase eventually faces the same conversation. The framework is several major versions behind. Upgrading is expensive, risky and invisible to customers. Not upgrading is cheaper this quarter and progressively more expensive every quarter after that.
The usual answer is a big-bang migration: freeze feature work, upgrade everything, spend weeks stabilising, and hope the regression surface is smaller than feared. We took a different route, and the sequencing turned out to matter more than any individual technical decision.
Subtract first, then upgrade
We ran the programme as two deliberately separated releases.
The first release added nothing. It removed dead code, unused assets, duplicate-capability libraries and entire retired UI frameworks that were still being shipped in the bundle. Platform versions were held deliberately steady. That constraint was the point: with the framework frozen, every measurement we took could be attributed to the clean-up and nothing else.
The second release performed the framework upgrade itself, onto a current vendor-supported generation, and retired an internally maintained fork of a rendering library that had been blocking upgrades for years.
The reason to subtract first is not tidiness. It is that every line you delete before a migration is a line you do not have to migrate, test, or debug afterwards. We removed 22 third-party libraries before touching the framework. That is 22 fewer compatibility surfaces, 22 fewer changelogs to read, and 22 fewer candidates when something breaks.
The most valuable change is the one nobody sees
The headline number was the download size. The genuinely important number was the 77% reduction in custom patch code.
A patch is a hand-written modification layered on top of a library you do not own. Patches are corrosive in a specific way: they must be reapplied and reverified every time the underlying library moves, they break in ways that are hard to attribute, and they quietly make every future upgrade more expensive than the last. Ours included a substantial internal fork of a graphics library.
Retiring that fork changed nothing a customer will ever notice, and changed almost everything about what the next upgrade will cost.
This is the part that is hardest to fund, because the return does not appear in the release it lands in. It appears in every release after.
"No change" was the hardest result to defend
Startup time and scroll performance came through the upgrade flat. Not improved — flat.
Holding customer-visible performance steady while replacing the rendering foundation is a genuine engineering result, but it is a difficult one to present. There is no chart that goes up. We were explicit with stakeholders in advance that flat was the target and the success criterion, so that when the numbers arrived unchanged, nobody read them as effort wasted.
One measurement nearly cost us a sprint
Midway through, an internal startup metric appeared to double. Read at face value, it implied the upgrade had badly regressed launch performance, and the obvious response would have been to send engineers to investigate.
Frame-by-frame capture on a physical device showed the home screen appearing at the same moment as before. The metric had shifted because the branded splash screen now correctly remained visible until the home screen was genuinely ready, instead of disappearing early and leaving customers watching empty loading states resolve. The app was equally fast and looked considerably more finished doing it.
The lesson
Instrumented metrics measure what they measure, not what you assume they mean. Before spending an engineering cycle on a regression, confirm it exists in the thing the customer actually experiences. We would have optimised a number that was never wrong.
Why the download size mattered more than it looks
A 23% reduction in download size reads like a vanity metric in markets with fast connections and recent hardware. It is not one in the emerging markets we were expanding into.
A smaller app installs faster, consumes less mobile data, and is far more likely to complete installation on a constrained data plan or a nearly-full entry-level device. That directly affects install and update conversion, and how quickly a new release actually reaches the customer base. Modernisation work that improves reach in your real market conditions is commercial work, not housekeeping.
What made it hold
The pattern I would carry to any similar programme:
- Separate the variables. Freeze platform versions during clean-up so results are attributable. Debugging a clean-up and a migration simultaneously is materially harder than doing them in sequence.
- Delete before you migrate. The cheapest code to upgrade is code you removed first.
- Set "no change" as an explicit success criterion when it genuinely is one, and say so before the numbers land rather than after.
- Verify regressions against reality before allocating engineers to them.
- Make it continuous. Every footprint and quality indicator improved in every release, not once in a clean-up sprint. That consistency is what signals a working practice rather than a temporary push — and it is why the gains held.
The programme cost real engineering capacity that could have gone to features. What it bought was a platform where the next upgrade is routine instead of exceptional. That trade is almost always worth making, and it gets more expensive the longer you wait to make it.