Feature flag pattern

Progressive release

Not every release needs to ship to everyone at once. Progressive release is the practice of gradually exposing a feature to an increasing percentage of users — starting with a small canary cohort, monitoring for issues, and expanding when confidence is established.

Progressive release manages each flag independently. Each flag defines its own rollout percentage and segment rules, advancing on its own schedule based on observed metrics. This makes it ideal for features that can be validated in isolation, where fine-grained, confidence-driven expansion matters more than coordinating a batch of changes together.

The key mechanism is the percentage rollout: each user is assigned a deterministic bucket between 0 and 99 based on their identifier. If that bucket falls below the rollout percentage, the user receives the feature. The same user always lands in the same bucket — which means as you expand the percentage, users who already received the feature continue to see it, and new users are progressively added without disrupting anyone already in the cohort.

Mental model

Three concepts to hold simultaneously

Progressive release combines percentage-based exposure, deterministic user assignment, and independent per-flag control. Understanding how they interact explains both the power and the constraints of the pattern.

Percentage targeting
Gradual exposure

Set a flag to 10% and roughly 1 in 10 users see the feature. Increase to 25% and those same users still see it — plus new ones. Rollback means setting the percentage back to 0.

Deterministic assignment
Consistent experience

A user's bucket is derived from their key, not random chance. The same user always gets the same result for a given percentage. This prevents flickering and makes rollout predictable.

Independent flags
Per-flag control

Each feature flag manages its own rollout independently. One flag can be at 50% while another is still at 1%. There is no batch coordination — each flag advances on its own schedule.

Rollback
Reduce, don't delete

Setting the percentage to 0 immediately removes the feature from all general users. Setting it back to 50% re-exposes the same cohort of users who saw it before — no new targeting setup required.

Evaluation model

How percentage rollouts evaluate

Every flag evaluation for a given user follows the same sequence. Segment rules evaluate first and can bypass the percentage check entirely — useful for giving developers or internal users guaranteed access during early phases.

User request Developer segment rule? explicit always-on for devs / internal match no match Assign user to bucket 0–99 deterministic — same user, same bucket, always bucket < rollout %? compare bucket to current percentage threshold yes no Flag → ON Flag → OFF fallthrough
Release lifecycle

From zero to GA

A progressive release moves through exposure phases, with a monitoring checkpoint between each one. The key discipline is not advancing until metrics confirm the previous phase is healthy. Each phase is a decision — not just a schedule.

Create feature flag default OFF, 0% rollout Developer validation developer segment always-on, 0% general Canary — 1% catch critical issues early, minimal blast radius Early access — 10% broader signal, monitor error rates and latency Broad rollout — 50% majority of users, high confidence required GA — 100% all users, set permanent default, retire flag rollback: set % to 0 or reduce Cleanup set default ON, archive flag, remove from codebase monitor between each phase
Quick reference

Key rules

01User bucket assignment is deterministic. The same user always lands in the same bucket for a given flag. Expansion includes the existing cohort plus new users — nobody loses access mid-rollout.
02Developer segment bypasses the percentage. Use segment targeting to guarantee developers and internal users always see the feature, regardless of their bucket. This is separate from the percentage rollout.
03Monitor before advancing. Each percentage increase is a decision, not a schedule. Check error rates, latency, and business metrics before expanding. The value of progressive release is the checkpoints.
04Rollback by reducing, not deleting. Setting the percentage to 0 removes the feature from general users while preserving the flag configuration. Ramping back up restores the same cohort.
05Each flag is independent. There is no shared gate or batch coordination. Each flag advances on its own schedule based on its own metrics. Cross-flag coordination requires external process discipline, not platform mechanism.
Interactive simulator

Configure and simulate a progressive rollout

Name your flags, step through each phase, and watch the user population respond as the percentage expands. Click any user to see their exact bucket value and per-flag evaluation result.