Rollout Planning

Flagship gives you complete control over how features are released to your users. Instead of a simple "on/off" switch, you define a Rollout Plan that determines who sees a feature and when.

A generic rollout plan consists of one or more Stages, which are executed sequentially.

Rollout Strategies

Different features require different rollout approaches. Flagship supports flexible strategies that can be mixed and matched within a single plan.

Percentage-based Rollouts

Percentage-based rollouts allow you to gradually increase the number of users who see a feature.

IMPORTANT

Percentages are Probability Buckets Flagship automatically hashes your targeting key to assign it a deterministic bucket between 0 and 100.

Effectively, a "10% rollout" is a rule: internalHash(targetingKey) % 100 < 10. You do not need to ensure your keys are normally distributed yourself; you only need to ensure they are unique. Flagship's hashing algorithm takes care of the distribution.

This deterministic approach ensures that:

1. Consistency: A user with the same targeting key will always fall into the same bucket.
2. Stickiness: As you expand from 10% to 50%, users who were in the 10% bucket stay in the 50% bucket.

Sample Size Warning

While Flagship's hashing ensures a uniform distribution over large numbers, the Law of Large Numbers applies. Percentages are probabilities, not exact counters.

• If you rollout 10% to 1,000,000 users, you will get very close to 100,000 users.
• If you rollout 10% to 10 users, you might get 0, 1, or 2 users, purely by chance.

Small Target Size

For small, safe user groups (e.g., "Internal Testers" or "Beta Users" with < 100 members), do not rely on percentages.

Instead of trying to target "10% of Beta Users", manually select the specific users you want to include and create a Target Group for them.

Example: If you have 50 Beta Users and want to test with 5 of them:

1. Bad: Rollout to Target Group: Beta Users AND Percentage: 10%. (You might get 0 users, or 8 users).
2. Good: Create a Target Group Beta Early Access with the specific 5 User IDs. Rollout to Target Group: Beta Early Access (100%).

Targeted Rollouts

For more controlled releases, you can target specific cohorts of users. This is essential for:

• Internal Testing: Release to employees first.
• Beta Programs: Release to opted-in users (e.g., plan == 'beta').
• Geo-fenced Releases: Release to specific regions (e.g., country == 'CA').

You can define these targets using ad-hoc Dimensions or reusable Target Groups. Using Target Groups is recommended for consistency across your organization.

Example: Tiered Rollout

A typical tiered rollout plan might look like this:

1. Stage 1: Target Group: Internal QA (100%)
2. Stage 2: Target Group: Beta Users (50%)
3. Stage 3: Global (10%)
4. Stage 4: Global (100%)

The Rollout Plan

A plan is composed of ordered Stages.

Stages

A stage defines a milestone in your rollout process. Each stage has:

• Name: E.g., "Canary", "Internal", "Public Scale-up".
• Target: Who is eligible for this stage? (e.g., "All Users" or a specific "Target Group").
• Allocation: What percentage of the target sees the feature? (e.g., 10%).

Flagship evaluates stages in order. A user matches the first stage where they meet the targeting criteria. If they don't match any specific targeting rules, they fall through to subsequent stages.

Auto-Progression

Flagship doesn't just toggle flags; it manages the lifecycle of your rollout.

1. Schedule: Define how quickly the rollout should progress (e.g., "Wait 2 hours between stages").
2. Confidence Windows: Every stage is monitored. If metrics remain stable, the next stage is triggered automatically.
3. Smart Halting: If a Warning Trigger fires, the AI halts the rollout, preventing further exposure while you investigate.

This "hands-off" approach allows you to deploy safely without staring at dashboards all day.

Best Practices

• Consistent Identity: Always pass a consistent userId in the Evaluation Context to ensure a user doesn't flip-flop between variations.
• Stateful Rollouts: Flagship remembers which users are in which bucket (sticky bucketing), ensuring a smooth experience even as you scale from 10% to 50%.
• Use Target Groups: Define common segments (like "Internal Team") as Target Groups once, and reuse them everywhere.