# Staged Rollouts

> Staged rollouts for mobile - percentage schedules, halt criteria, feature flags, and coordinating App Store Phased Release with Play Store staged rollout. Use when planning any production release.

- Skill: `almasumdev/staged-rollouts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add almasumdev/staged-rollouts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/almasumdev/staged-rollouts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: almasumdev (https://skillmd.com/u/almasumdev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/almasumdev/staged-rollouts

---


# Staged Rollouts

## Instructions

Never ship a new mobile version to 100% of users at once. The point of a staged rollout is to catch the regressions your QA missed before they become a one-star-review avalanche or a rollback that you cannot execute (you cannot force users to downgrade).

### 1. Why Staged

- **No instant rollback.** A bad mobile build stays installed. Only new installs can receive a fix. Staging buys time.
- **Heterogeneity.** OS versions, device models, locales, carriers. Staged cohorts sample this variance.
- **SDK surprises.** New or updated SDKs can crash in production configurations you did not anticipate.
- **Store review latency.** A hotfix can take hours to days. Staged exposure is your primary safety net.

### 2. Canonical Percentage Schedule

| Step | iOS (Phased Release) | Android (staged rollout) | Wait time |
| --- | --- | --- | --- |
| 1 | 1% | 1-5% | 24-48h |
| 2 | 2% | 10% | 24h |
| 3 | 5% | 20% | 24h |
| 4 | 10% | 50% | 24h |
| 5 | 20% -> 50% -> 100% | 100% | automatic after holds met |

Hold longer on the first step if the release includes new SDKs, major refactors, or schema migrations.

### 3. Halt Criteria

Write halt criteria before the release, not during incidents.

- **Crash-free sessions** drops more than 0.3 pp vs baseline -> halt.
- **Crash-free users** drops more than 0.2 pp vs baseline -> halt.
- **ANR rate** on Android doubles -> halt.
- **Key funnel conversion** (sign-in, checkout) drops more than 5% relative -> halt.
- **Single crash** hitting more than 0.1% of users -> halt until fixed.
- **Store review delta** below -0.3 stars within 6 hours of a step -> investigate before proceeding.

Halting is cheap. Ship the fix, resume the rollout from the halted step.

### 4. Feature Flags and Kill Switches

Staged rollout of the binary is coarse. Feature flags are fine-grained and instantaneous. Pair them.

- Every risky feature sits behind a server-side flag.
- Flags support: on/off global, percentage rollout, per-segment (country, platform, app version).
- Include a **local fail-closed** default: if the config service is unreachable, the flag evaluates to the safe value.
- Include a **kill switch** per feature: a flag that disables the feature regardless of other logic.

```kotlin
val flags = FeatureFlags.current()
val checkoutV2 = flags.boolean("checkout_v2", default = false)
val newPaymentFlow = flags.percentage("payment_flow_v2", default = 0.0)
```

Providers: LaunchDarkly, Firebase Remote Config, Unleash, self-hosted via a simple JSON endpoint on a CDN. Keep evaluation deterministic (hash userId) so a user stays in the same cohort across sessions.

### 5. Observability Hooks

Tag every metric and crash with the version and flag state.

- `app.version`, `app.build`, `flag.<name>` as dimensions.
- Dashboards show crash-free sessions per version and per flag.
- Alerts target the current release cohort, not global aggregates.

### 6. iOS Specifics

- App Store Phased Release is automatic once enabled, in daily 1/2/5/10/20/50/100 steps. You can pause and resume via App Store Connect.
- **Pausing** stops new users from getting the update; users who already updated keep it.
- Expedited reviews exist for serious issues and can cut review to hours.

### 7. Android Specifics

- Play staged rollout is configured per release track; you choose the percentage.
- **Halt rollout** stops new installs at the current version; users on it keep it.
- You can **resume at the same or a new percentage**. Bumping percentage works; lowering does not.
- Consider **in-app updates** (flexible or immediate) to nudge users toward the fix once shipped.

### 8. Data Migrations in Staged Rollouts

Migrations are the riskiest part of any rollout.

- Write migrations to be **idempotent** and **forward-only** where possible.
- Add **dry-run and metrics** to the migration itself (counts, timings, failures).
- Gate risky migrations behind a feature flag so an existing install can stay on the old schema until a follow-up release.
- Never require a server change synchronized to a client version; handle versions overlap explicitly.

### 9. Rollout Playbook

Write a brief playbook for each release:

```markdown
# Release 2.5.0 Rollout

## Baselines (from 2.4.x)
- Crash-free sessions: 99.85%
- Crash-free users: 99.6%
- ANR rate: 0.09%

## Schedule
- iOS: Phased Release on, monitor daily.
- Android: 5% -> 20% -> 50% -> 100% with 24h holds.

## Halt criteria
- Crash-free sessions drop > 0.3pp
- Checkout conversion drop > 5%
- Any crash > 0.1% of users

## Kill switches
- flag: checkout_v2
- flag: new_sync_engine

## Owners
- Release manager: @alice
- Pager primary: @bob
- Pager secondary: @carol

## Rollback plan
- Halt immediately
- Ship hotfix branch from main (cherry-picked)
- Expedited review if iOS
```

### 10. Anti-Patterns

- "Staged rollout" that promotes every 2 hours. Too fast to see regressions.
- Halting, fixing, and resuming without a new baseline. Check the data.
- Feature flags without a kill switch for the whole feature.
- Long-lived flags. Remove after full rollout; they become a maintenance tax.
- No baseline. "Crash-free 99.7%" means nothing without the prior version number.

## Checklist

- [ ] Baseline metrics from the prior version are recorded before the rollout.
- [ ] A written halt criteria document exists with absolute thresholds.
- [ ] Risky features are behind feature flags with kill switches.
- [ ] Feature flag evaluation is deterministic per user and fails safe.
- [ ] Metrics and crashes are tagged with version and flag state.
- [ ] iOS Phased Release is enabled; Android staged rollout percentages are set.
- [ ] Rollout playbook names owners and escalation path.
- [ ] Rollback plan covers hotfix and expedited review steps.
- [ ] Stale feature flags are removed after full rollout.