When to Raise Your Minimum iOS Version — Count Leftover Branches, Not User Percentages

Count what each candidate floor would retire

Once the annotations exist, the rest is arithmetic.

The script below walks src, collects the annotations, and reports a cumulative count of how many branches disappear at each candidate floor. It also flags two failure modes: annotations that have already fallen below the current floor, and untagged OS checks that the inventory can't see.

#!/usr/bin/env node
// scripts/os-sweep.mjs
// Inventory of OS branches. Answers: if I raise the floor to X,
// how many branches can I delete?
import { readFileSync } from 'node:fs';
import { readdir } from 'node:fs/promises';
import { join, extname, relative } from 'node:path';
 
const ROOT = process.argv[2] ?? 'src';
const MATRIX = process.argv[3] ?? 'src/config/supportMatrix.ts';
const EXT = new Set(['.ts', '.tsx', '.js', '.jsx']);
const SKIP = new Set(['node_modules', '.git', 'ios', 'android', 'dist', '.expo']);
const TAG = /@drop-when\s+ios>=\s*([0-9]+(?:\.[0-9]+){0,2})(?:\s*--\s*(.*))?/;
const CALL = /atLeastIOS\(\s*['"]([0-9]+(?:\.[0-9]+){0,2})['"]\s*\)/;
 
/** "16.4" becomes 160400 so versions compare as integers. Bad input returns null. */
function toNum(v) {
  const parts = String(v).split('.').map((n) => Number.parseInt(n, 10));
  if (parts.some((n) => !Number.isInteger(n) || n < 0)) return null;
  const [a = 0, b = 0, c = 0] = parts;
  return a * 10000 + b * 100 + c;
}
 
function readMinIOS(path) {
  let src;
  try {
    src = readFileSync(path, 'utf8');
  } catch (e) {
    throw new Error(`cannot read the OS floor definition: ${path} (${e.code ?? e.message})`);
  }
  const m = src.match(/ios\s*:\s*['"]([0-9][0-9.]*)['"]/);
  if (!m) throw new Error(`no ios: "x.y" definition found in ${path}`);
  const n = toNum(m[1]);
  if (n === null) throw new Error(`invalid ios value in ${path}: ${m[1]}`);
  return { raw: m[1], num: n };
}
 
async function* walk(dir) {
  let entries;
  try {
    entries = await readdir(dir, { withFileTypes: true });
  } catch (e) {
    if (e.code === 'ENOENT') return;
    throw e;
  }
  for (const e of entries) {
    if (e.name.startsWith('.')) continue;
    const p = join(dir, e.name);
    if (e.isDirectory()) {
      if (SKIP.has(e.name)) continue;
      yield* walk(p);
    } else if (EXT.has(extname(e.name))) {
      yield p;
    }
  }
}
 
let min;
try {
  min = readMinIOS(MATRIX);
} catch (e) {
  console.error(`os-sweep: ${e.message}`);
  process.exit(2);
}
 
const tagged = [];   // annotated, above the floor
const untagged = []; // OS checks with no annotation
const stale = [];    // already below the floor, deletable today
 
for await (const file of walk(ROOT)) {
  const lines = readFileSync(file, 'utf8').split('\n');
  const annotated = new Set();
  lines.forEach((line, i) => {
    const t = line.match(TAG);
    if (t) {
      const num = toNum(t[1]);
      if (num === null) {
        console.error(`  ! malformed version: ${relative('.', file)}:${i + 1} -> ${t[1]}`);
        return;
      }
      const rec = {
        file: relative('.', file), line: i + 1,
        version: t[1], num, reason: (t[2] ?? '').trim(),
      };
      // Treat the next three lines as the branch this annotation guards
      for (let k = i; k < Math.min(i + 4, lines.length); k++) annotated.add(k);
      (num <= min.num ? stale : tagged).push(rec);
    }
    if (CALL.test(line) && !annotated.has(i)) {
      untagged.push({ file: relative('.', file), line: i + 1, version: line.match(CALL)[1] });
    }
  });
}
 
const byVersion = new Map();
for (const t of tagged) byVersion.set(t.version, (byVersion.get(t.version) ?? 0) + 1);
const sorted = [...byVersion.entries()].sort((a, b) => toNum(a[0]) - toNum(b[0]));
 
console.log(`current minimum iOS: ${min.raw}`);
console.log(`annotated OS branches: ${tagged.length} / untagged: ${untagged.length}`);
console.log('');
console.log('branches retired per candidate floor (cumulative):');
let acc = 0;
for (const [v, n] of sorted) {
  acc += n;
  console.log(`  raise to iOS ${v.padEnd(6)} -> ${String(acc).padStart(3)} branches go away`);
}
if (stale.length) {
  console.log('');
  console.log(`WARN ${stale.length} branch(es) already below the floor (${min.raw}) and deletable now:`);
  for (const s of stale) console.log(`  ${s.file}:${s.line}  ios>=${s.version}  ${s.reason}`);
}
if (untagged.length) {
  console.log('');
  console.log(`WARN ${untagged.length} untagged OS branch(es) — invisible to this inventory:`);
  for (const u of untagged) console.log(`  ${u.file}:${u.line}  atLeastIOS('${u.version}')`);
}
process.exitCode = stale.length > 0 ? 1 : 0;

Run against a sample tree, it prints this:

$ node scripts/os-sweep.mjs src src/config/supportMatrix.ts
current minimum iOS: 16.0
annotated OS branches: 3 / untagged: 1
 
branches retired per candidate floor (cumulative):
  raise to iOS 16.4   ->   1 branches go away
  raise to iOS 17.0   ->   2 branches go away
  raise to iOS 18.0   ->   3 branches go away
 
WARN 1 branch(es) already below the floor (16.0) and deletable now:
  src/screens/Settings.tsx:2  ios>=15.0  left behind after the last bump
 
WARN 1 untagged OS branch(es) — invisible to this inventory:
  src/lib/os.ts:3  atLeastIOS('17.2')

Having that list in front of you changes the conversation you have with yourself.

It stops being "do I cut 0.9 percent of users" and becomes "raising to 17.0 retires this many branches I'm currently carrying." The first is a question about feelings. The second is an estimate.

The run itself is cheap. I seeded a tree of 1,000 files carrying 2,000 annotations and timed three consecutive runs: 0.08, 0.09, and 0.09 seconds. You can put it in a pre-commit hook without anyone noticing.

Fail CI on the leftovers

The payoff in daily use turned out to be the stale-branch detection, not the projection table.

You raise the floor to 16.0 but an ios>=15.0 branch is still sitting in the code. That's dead code. It costs a reader's attention and makes every future edit to that file slower, because someone has to satisfy themselves that the other path doesn't matter.

Three exit codes:

Untagged branches only warn. Making them fail would force a mass annotation pass across the existing codebase before anyone could merge anything, and that's exactly how a convention dies on arrival. New branches get annotated; old ones get annotated when you happen to touch them. That ordering is the only version of this I've managed to sustain.

The Actions wiring is one step:

# .github/workflows/quality.yml (excerpt)
      - name: OS branch inventory
        run: node scripts/os-sweep.mjs src src/config/supportMatrix.ts

Any pull request that raises the floor now goes red automatically, and the list of branches to delete is already sitting in the CI log. No runbook lookup required.

For the release mechanics I reuse what I set up in A Phased Release Strategy for Rork Apps — How I Combine iOS Phased Release, Android Staged Rollout, and OTA Hotfixes for a Production That Doesn't Break. A floor bump is harder to roll back than a feature, so it belongs in a phased release without exception.

Put the Android floor in the same ledger

About six months in, I found an embarrassing gap.

supportMatrix.ts had carried android: 31 from the very first day. The sweep only ever read the ios line. So the Android floor stayed scattered across three places — my own memory, the Play Console screen, and the native build settings — while I congratulated myself for having a single source of truth.

I had written "stop defining the floor twice" into the tool, and then failed to count the other platform at all. A ledger that covers one platform hides the debt on the other.

The fix is small. Put the platform into the annotation format, then read two floors and keep two buckets.

// 1. Capture the platform in both patterns
const TAG  = /@drop-when\s+(ios|android)>=\s*([0-9]+(?:\.[0-9]+){0,2})(?:\s*--\s*(.*))?/;
const CALL = /atLeast(IOS|Android)\(\s*['"]?([0-9]+(?:\.[0-9]+){0,2})['"]?\s*\)/;
 
// 2. Read both floors (Android is an integer API level)
function readMin(path) {
  const src = readFileSync(path, 'utf8');
  const mi = src.match(/ios\s*:\s*['"]([0-9][0-9.]*)['"]/);
  const ma = src.match(/android\s*:\s*['"]?([0-9]+)['"]?/);
  if (!mi) throw new Error(`${path} has no ios: "x.y" entry`);
  if (!ma) throw new Error(`${path} has no android: NN entry`);
  return { ios: { raw: mi[1], num: toNum(mi[1]) }, android: { raw: ma[1], num: toNum(ma[1]) } };
}
 
// 3. Tally per platform
const empty = () => ({ tagged: [], untagged: [], stale: [] });
const buckets = { ios: empty(), android: empty() };
// …when an annotation matches, read plat = t[1] and push into buckets[plat]

toNum folds "16.4" into an integer like 160400, so a bare API level such as 31 passes through unchanged. Android needs no separate comparator.

The annotation side looks like this:

// @drop-when android>=33 -- the explicit notification permission prompt lands in API 33
if (!atLeastAndroid(33)) {
  return <LegacyNotificationPrompt />;
}

Running it against my sample tree:

$ node scripts/os-sweep.mjs src src/config/supportMatrix.ts
[iOS] current floor: 16.0
  annotated: 4 / unannotated: 1
    iOS 16.4   ->   1 branch(es) retired
    iOS 17.0   ->   2 branch(es) retired
    iOS 17.2   ->   3 branch(es) retired
    iOS 18.0   ->   4 branch(es) retired
    ! stale  src/screens/Settings.tsx:1  ios>=15.0  already below the floor
    ! untagged  src/screens/Legacy.tsx:1  17.2
 
[Android API] current floor: 31
  annotated: 1 / unannotated: 1
    Android API 33     ->   1 branch(es) retired
    ! stale  src/screens/Settings.tsx:5  android>=30  already below the floor (31)
    ! untagged  src/screens/Legacy.tsx:2  34

The exit code turns 1 if either platform still has a stale branch. Going green on one platform alone tells you nothing useful.

What surprised me once I could see both columns is that the debt has a different shape on each side. The iOS branches cluster around rendering and share sheets; the Android ones cluster around permissions and background execution. A single Android bump often retires a whole cluster of permission branches at once, so measured purely in branches retired, Android sometimes offered the better return.

That said, Play's target API level requirements move every year, so on Android there is even less room to decide than on iOS. I've come to treat the date as fixed and spend my judgment only on the order in which the branches come out.

Three things I had wrong

After roughly six months of running this, several of my assumptions turned out to be false.

Dropping support freezes the app; it doesn't remove it

I believed for years that raising the minimum made the app disappear from the App Store on older devices.

It doesn't. A user who already owns the app and re-downloads it from their purchase history receives the last version compatible with that device. The app stays. It just stops moving.

That's a mercy and a liability at the same time. The build you thought you had retired keeps running in the wild, which means support requests and one-star reviews from it keep arriving — and you can no longer ship a fix to that build.

So the real preparation happens before the bump. In the release immediately preceding it, I clear whatever known issues I can and confirm that the server API won't start rejecting older clients. You are choosing the state this build will be frozen in, so choose it deliberately.

I wasn't actually the one deciding

The second misconception was that I controlled the timing.

Rork generates Expo-based React Native apps, and each Expo SDK release raises its own OS floor. Skipping SDK upgrades isn't a real option — eventually builds and store submissions stop going through.

So what I actually control isn't whether to raise the floor. It's how far ahead of the SDK's schedule I finish preparing for it.

Once that landed, I moved the decision earlier in the calendar. When SDK release notes mention a floor change, that value goes into supportMatrix.ts as a candidate, and I run the sweep against it to see what would be retired. The scramble on upgrade day disappeared.

Which floor a given SDK requires changes release to release, so check the notes rather than memorizing a number — anything you memorize today will be wrong next year.

The post-bump improvement isn't an improvement

The week after a bump, my crash-free rate visibly improved.

I nearly wrote that down as a result, then stopped. Nothing about the code had gotten better. What disappeared were branches, not defects. The number moved because the oldest, most crash-prone device generation left the sample.

Logging that as "the payoff from raising the floor" poisons next year's decision. All that survives is the memory that last time, the numbers got better — and you make the next call expecting a benefit that was never real.

Now I compare before and after using only the OS versions that survive the bump. Hold the population fixed and, in most cases, almost nothing moves. That's the honest picture.

For the collection layer underneath all this, I use the pipeline from Rork × MetricKit — Building a Solo Diagnostics Pipeline for Crashes, Hangs, and Battery Drain, sliced by OS version.

Three ways this bit me

Six months in, a few things tripped me up. Here are the ones I'd warn someone about.

The floor ends up defined in two places

This was the worst of them. I kept calling supportMatrix.ts the single source of truth while the value that actually governed the binary lived somewhere else.

In Expo, the native minimum comes from the build deployment target. Change supportMatrix.ts to 17.0 and leave that at 16.0, and the binary in the store still supports 16.0. Meanwhile the sweep happily reports stale branches on the assumption you raised it. That mismatch is the dangerous one, because everything looks consistent from the inside.

The fix is to stop writing the value twice and have the build config read the source of truth.

// app.config.ts
import { MIN_OS } from './src/config/supportMatrix';
 
export default {
  expo: {
    // ...
    plugins: [
      [
        'expo-build-properties',
        {
          ios: { deploymentTarget: MIN_OS.ios },
        },
      ],
    ],
  },
};

Plugin names and key shapes shift between SDK versions, so confirm the details against your own. The part that matters is simply that the number exists in one place.

The three-line window around an annotation can hide a call

The sweep treats the three lines following an annotation as the branch that annotation protects. It's a shortcut that assumes an if and its body sit directly underneath.

There is one shape where the shortcut misfires. Stack two or three annotated branches back to back, then write a bare atLeastIOS(...) immediately below them: the last annotation's window reaches that line, and the unannotated call slips through as if it were covered. I hit this in the sample tree. Moving the call down by a single line was enough to make the warning appear.

Widening the window doesn't fix it either — the wider it gets, the more unrelated calls it swallows as "already annotated." I left the window at three lines and covered the gap with the ESLint rule in the next section instead. Where one detector has a hole, the other detector covers it. Trying to make a single script airtight leaked more than running two imperfect ones side by side.

Direct Platform.Version reads are a back door

Even with a helper available, older code and rushed fixes reach for Platform.Version directly. The sweep can't see those, so they quietly fall outside the inventory.

I closed that with a lint rule.

// eslint.config.js (rule only)
{
  rules: {
    'no-restricted-syntax': [
      'error',
      {
        selector: "MemberExpression[object.name='Platform'][property.name='Version']",
        message: 'Do not read Platform.Version directly — use atLeastIOS from src/lib/os.ts',
      },
    ],
  },
}

You'll need an override so src/lib/os.ts itself is exempt.

The frozen build freezes your SDKs too

This one I only understood in hindsight.

When you raise the floor, older devices keep the last compatible version — and every ad and billing SDK inside it is pinned at that version forever. In areas where the vendor can change policy on their side, such as AdMob, that eventually matters. If ads stop rendering in the frozen build, there is no path to ship a fix.

If any meaningful revenue sits on those devices, upgrade the SDKs in the build you're about to freeze, before you freeze it. I missed this once and watched revenue from the frozen side thin out over several months before I worked out why.

One more piece of sizing advice: if you ship a single app, you don't need any of this tooling. The annotation habit alone is enough. If you run several in parallel and share code through an internal package, put the sweep in that package instead. Shared code gets dragged down to the lowest floor among its consumers, and the report makes it immediately obvious which app is doing the dragging.

The sequence I follow

1. Run the sweep and note how many branches each candidate floor retires
2. Check the Expo SDK release notes for the next required floor
3. In App Store Connect, look at session share and revenue for the versions you're about to drop (usage share is not the deciding input — it's the cost you're agreeing to accept)
4. In the release before the bump, clear known issues in what will become the frozen build
5. Confirm the server API still accepts requests from older clients
6. Update supportMatrix.ts, watch CI go red, and delete the branches it lists
7. Ship it through a phased release

Step 3's position in the list is the whole point. Look at usage share first and thinking stops there. Look at the branch count first and usage share becomes a question of whether you're willing to accept the loss — same number, different job, decided entirely by ordering.

What I watch for 30 days after

I didn't track the third one originally. Active devices once dropped further than projected after a bump, and the cause turned out to be an unrelated change shipped the same day. Since then, floor bumps go out on their own.

Where to start

How many OS branches are in your codebase right now? You probably can't answer. I couldn't either.

Start with a single comparison helper and annotate only the branches you write from here on. There's no need to backfill. Within a couple of quarters the inventory will be complete enough to decide with.

Once you can count them, deferring stops being "not making a decision" and becomes "knowingly carrying visible debt for another year." You might still choose to wait — but you'll be able to say why.

Thank you for reading this far. Small, unglamorous instrumentation like this is what makes the long haul survivable.