How to plan an app v2 update without breaking v1

Planning an app v2 update is the point where most small products get into trouble. Version one is forgiving, because nobody is using it yet. Version two has real users, real data, and real reviews waiting to punish a bad release. The teams that get through it calmly are not the ones with the most engineers, they are the ones that made four decisions before writing any code: what actually changes, what hides behind a flag, what happens to the API, and what happens to the data. This is the sequence we use with Bluka clients on every second version.

What planning an app v2 update actually means

To plan an app v2 update is to decide, in advance, which changes can reach users gradually and which cannot, then build the release so that v1 keeps working for everyone who has not updated yet. It is a compatibility plan first and a feature plan second.

That order matters. Founders usually arrive with a feature list for v2 and treat compatibility as an engineering detail to sort out later. In practice compatibility is what determines how the features get built, how long the release takes, and whether a bad week can be undone in an afternoon. Sorting it out later means sorting it out during an incident.

What you need before you start

You do not need a technical background to run this process, but you do need four inputs on the table:

• Real usage data from v1, broken down by screen and by feature.
• The list of API endpoints your app calls, and anything else that calls them.
• The share of your users sitting on each installed app version.
• A clear statement of what v2 is meant to improve, in one sentence.

If the usage data does not exist yet, that is the first problem to fix, and it is a bigger one than v2. Our guide to app analytics from day one covers the minimum set of events worth tracking before you plan any second version.

Step 1: measure v1 before you redesign it

Almost every v2 plan starts with a meeting where people say what they think is wrong with v1. Those meetings are useful for generating hypotheses and useless for deciding scope. Before anything gets on the roadmap, pull the numbers: which screens people reach, which features they touch more than once, where they abandon a flow, and which parts of the product nobody has opened in ninety days.

The result is almost always uncomfortable. Features the team argued about for weeks turn out to have a handful of users. A screen nobody discussed carries most of the engagement. Good v2 scope comes from that gap between what the team believes and what the data shows, and it usually makes the release smaller rather than larger. That is the point. A v2 that removes two dead features and improves one heavily used flow will beat a v2 that adds five new things on top of a product people already find confusing.

Step 2: sort every change into additive, replacing, or destructive

Once you have a candidate list, classify every item into one of three buckets. This is the single most useful half hour of the whole plan.

Additive changes can ship whenever they are ready. Replacing changes need both versions running for a while. Destructive changes are the only ones that can genuinely break v1, and they deserve most of your attention, most of your testing time, and a firm answer to the question “what do we do if this goes wrong at 9am on a Monday”. In a healthy v2, the destructive list should be short, and every item on it should be there because it unblocks something, not because it tidies things up.

Step 3: put feature flags in before you write v2 code

A feature flag is a switch that decides whether a piece of code runs, controlled from the server rather than from the app store. It sounds like infrastructure overhead until the first time you turn off a broken feature in thirty seconds instead of waiting two days for a review.

The rule we hold to is that every new feature in an app v2 update is born switched off. The code ships, the flag stays closed, and the feature is opened for the team first, then a small share of users, then everyone. This separates deployment from release, which is the whole game: it means the code being live and the feature being live are two different events you control independently.

Flags also make the release calendar less brittle. When one feature is not ready, it stays dark and the rest of the release ships on time, rather than the entire version waiting for its slowest part. What flags do not give you is permission to skip testing. A flag limits the blast radius of a mistake; it does not prevent the mistake.

Step 4: version the API instead of editing it

Here is the thing that catches non-technical founders by surprise: users do not all update at once. Weeks after a v2 release, a meaningful share of people are still running v1, and their app is still calling your backend. If you change what an existing endpoint returns, you break their app without touching their phone.

The fix is to add rather than edit. Publish v2 endpoints alongside the v1 ones, point the new app at the new endpoints, and keep the old ones answering until the population on old versions is small enough to retire. It costs a little duplication for a few months and it removes the single most common cause of a v2 release going wrong.

Both stores give you the data to make that call. Apple’s App Store Connect documentation and Google’s Play Console guidance both expose the distribution of installed versions, which is the number that tells you when v1 support can end. Decide the retirement rule from that number rather than from a date you picked at the start.

Step 5: plan the data migration with a way back

Data migrations are where v2 releases become genuinely expensive, because a bad one is not always reversible. The pattern that keeps them safe has three phases and is worth the extra week it takes.

First, write to both the old and the new shape at the same time, while still reading from the old one. Second, backfill the existing records and compare the two sources until they agree. Third, switch reads to the new shape, and only then stop writing the old one. At every point in that sequence you can stop and go back without losing anything, which is not true of a migration that flips everything in one release.

The other half of the plan is the rollback itself. Write down, before release day, what the team does if the migration goes wrong: who makes the call, how long you wait before making it, and what the exact steps are. A rollback plan invented during an incident is not a plan, it is a group of tired people guessing.

Step 6: release in stages and watch the numbers

Resist the release that goes to everyone on a Friday. Start with a small share of users, let it run long enough to gather real behaviour rather than first-day novelty, and compare that group against the people still on v1. Both stores support staged rollouts natively, so this costs you patience rather than engineering.

Decide the comparison before you start. Activation, retention at day seven, crash rate, and the one metric v2 was supposed to improve are usually enough. If the split test shows the new version behind on any of them, the correct move is to pause the rollout and find out why, not to push on and hope the average recovers at scale. It rarely does. A staged release only protects you if you are genuinely willing to stop it.

How to know it worked

A v2 update went well when three things are true a month later: crash rates are at or below v1 levels, the metric you set out to improve has actually moved, and support is not fielding a queue of people whose data looks wrong. Reviews are a lagging and noisy signal, but a sharp drop in rating within a fortnight of release is worth treating as an incident rather than a mood.

What you should not see is a rush of hotfixes. A release that needs four emergency patches in its first week was not a planning failure at the feature level, it was a compatibility failure, and it usually traces back to a destructive change that skipped Step 2. The month after launch is where those costs land, and it is worth reading before you commit to a date.

What to do next

Write the four decisions down before the roadmap: what the data says v2 should fix, which changes are destructive, how the API keeps serving v1, and what the migration rollback looks like. That document takes a couple of days and reliably saves weeks. If it raises more questions than it answers, that is a useful result too, and it usually means the scope is still too big. Our checklist for scoping an app project works just as well on a second version as a first.

If you would rather have someone run this with you, send us a project brief and we will tell you honestly whether your v2 needs a studio, a single engineer, or simply a smaller plan.