Store Release

Shipping a web application is one action with one outcome: you deploy, and the next request serves the new code. Shipping a mobile application is a sequence with several parties in it, at least one of which can say no, and the last step belongs to your users rather than to you.

Three things stand between a finished build and an engineer using it. The store listing has to be complete and accurate. A reviewer has to approve the build, which takes time and sometimes ends in a rejection. And then each user has to install the update, on their own schedule, which for a meaningful fraction of them is never.

Everything difficult about mobile releases comes from the last point, and it deserves stating plainly at the start: you cannot recall a release. Once a build has reached users, those users have that build. You can stop the rollout to people who have not updated yet, and you can submit a fix and wait, but you cannot take a bad version off the devices that already have it. The consequences of that are architectural, and they are the subject of the second half of this lesson.

{
  "configVersion": 47,
  "minimumSupportedVersion": "4.1.0",
  "features": {
    "photoAttachments": "on",
    "routeOptimiser": "off",
    "offlineQueueRewrite": "internal"
  },
  "notice": {
    "level": "warning",
    "text": "Update the app to keep syncing visit notes"
  },
  "maxAgeSeconds": 900
}

• The field names are invented for this lesson and the document is served by your own API rather than by a platform service. The shape is the transferable part: a few switches, a version floor, and something you can say to the user.
• minimumSupportedVersion is the forced-update lever. It has to be decided on the server, because the one thing you cannot do is change the behaviour of an app already installed on a device. A build that reads this can be told to stop; a build that does not read it cannot.
• The feature switches have three states rather than being booleans. On and off give you the ability to disable one broken feature without a release, which is the difference between a bad afternoon and a bad week. The internal state lets a feature reach your own testers through the real store build, so it is exercised on real devices before anybody else sees it.
• The notice is there because silence is the worst option during an incident. If photo attachments are switched off, an engineer standing in front of a piece of equipment needs to know that, and telling them is cheaper than the support calls.
• maxAgeSeconds means the app caches this document. That matters more than it looks: an app that refuses to start until a configuration fetch succeeds has made your configuration endpoint a single point of failure for every device, including the ones in a basement. Cache the last good copy, and start with it when the fetch fails.
• configVersion is for you, not the app. When somebody reports odd behaviour, knowing which configuration their device had at the time is frequently what closes the investigation.
• Keep this document small and cheap. It is fetched on every cold launch, so it is the wrong place for anything large, and nothing in it should be confidential — it travels to every installation, exactly like the app itself.

type StartupGate =
  | { kind: "run" }
  | { kind: "forceUpdate"; text: string }
  | { kind: "notice"; text: string };

interface RemoteConfig {
  minimumSupportedVersion: string;
  features: Record<string, "on" | "off" | "internal">;
  notice?: { level: "info" | "warning"; text: string };
}

/** Numeric comparison, because "4.10.0" sorts before "4.9.0" as a string. */
function isOlderThan(installed: string, required: string): boolean {
  const left = installed.split(".").map(Number);
  const right = required.split(".").map(Number);

  for (let i = 0; i < 3; i += 1) {
    const a = left[i] ?? 0;
    const b = right[i] ?? 0;
    if (a !== b) return a < b;
  }
  return false;
}

export function startupGate(
  installedVersion: string,
  config: RemoteConfig | null,
): StartupGate {
  if (config === null) return { kind: "run" };

  if (isOlderThan(installedVersion, config.minimumSupportedVersion)) {
    return { kind: "forceUpdate", text: "This version can no longer sync. Update to continue." };
  }

  if (config.notice) return { kind: "notice", text: config.notice.text };
  return { kind: "run" };
}

export function featureEnabled(
  config: RemoteConfig | null,
  name: string,
  buildDefault: boolean,
  isInternalUser: boolean,
): boolean {
  const state = config?.features[name];
  if (state === undefined) return buildDefault;
  if (state === "internal") return isInternalUser;
  return state === "on";
}

• As with every sample in this course, the shape is what transfers. Reading the installed version and opening a store page are platform calls that look nothing like this.
• A null configuration returns run, which is the most important line here. Failing open means a device with no connection still launches into the offline experience you built. Failing closed would mean your configuration endpoint having a bad five minutes takes every device offline, which is a larger outage than most of the problems this mechanism exists to contain.
• That is a genuine trade-off, stated honestly: a kill switch cannot reach a device that does not connect, and a forced update cannot stop a build that never asks. This mechanism limits the blast radius of a bad release; it does not eliminate it.
• The version comparison is written out because comparing version strings directly gets 4.10.0 and 4.9.0 the wrong way round. It is a small bug with a large effect, since it decides whether you block the wrong users.
• A forced update is a blocking screen that stops somebody working, so treat it as a serious step reserved for data loss, a security problem or a client that can no longer talk to your API safely. The text has to say why and lead straight to the store page, and a user with no connection needs to be told that too rather than being left on a dead screen.
• featureEnabled takes the build's own default so an unknown switch behaves the way that build was tested to behave. Defaulting everything to off would silently disable features on an older client the moment you rename a switch.
• Both functions are pure, so the rules are testable without a device or a server: assert that an old build is gated, that a current one runs, and that a missing configuration never blocks the app.