Star
Build

Percentage rollouts

Start at 5%, watch your graphs, widen. Each user lands in the same bucket every time, so widening a rollout only adds people. Nobody bounces between the old checkout and the new one.

Weights, not percentages

A rollout splits contexts between variations by weight, an integer out of 100,000. The weights must add up to exactly 100,000.

You wantWeights
5% on[{ variation: 1, weight: 5000 }, { variation: 0, weight: 95000 }]
20% on[{ variation: 1, weight: 20000 }, { variation: 0, weight: 80000 }]
A 50/50 test[{ variation: 1, weight: 50000 }, { variation: 0, weight: 50000 }]
0.1%[{ variation: 1, weight: 100 }, { variation: 0, weight: 99900 }]

Use it as the fallthrough (everyone not matched by a target or rule), or inside a rule to roll out to part of a group.

curl -X PATCH https://flags.acme.com/v1/admin/projects/acme/environments/production/flags/new-checkout \
        -H "Authorization: Bearer $FEATUREKIT_TOKEN" -H "Content-Type: application/json" \
        -d '{
          "expectedVersion": 413,
          "enabled": true,
          "fallthroughRollout": { "variations": [{ "variation": 1, "weight": 20000 }, { "variation": 0, "weight": 80000 }] }
        }'

Why widening only adds people

Each context is hashed into one of 100,000 buckets. Variations take the buckets in order:

bucket = murmur3("${flagKey}.${salt}.${contextKey}") * 100000 / 2^32

      at 20%:  buckets 0 – 19,999   → on      everyone else → off
      at 50%:  buckets 0 – 49,999   → on      the first 20% are still in

A context's bucket never moves, so going from 20% to 50% keeps the original 20% and adds 30% more. Going back down removes the most recent additions first.

  • The flag key is in the hash, so two flags at 10% don't go to the same 10% of users.
  • The environment's salt is in the hash, so staging's 10% isn't production's 10%.
  • It's integer math, identical in every language, and checked against a shared conformance corpus.
Keep the order of variations

Buckets are assigned in the order the variations are listed. Listing off before on at the same weights reshuffles who gets what. The MCP server keeps the order for you.

Roll out by organization, not user

Set contextKind and everyone in an organization flips together, instead of half an org seeing the new thing:

"fallthroughRollout": {
        "contextKind": "organization",
        "variations": [{ "variation": 1, "weight": 10000 }, { "variation": 0, "weight": 90000 }]
      }

bucketBy hashes another attribute instead of the key. A context without that attribute (or without that kind) is left out of the rollout rather than dumped into the first variation. In a rule, the rule doesn't match and evaluation moves on. At the fallthrough there's nowhere left to go, so it gets your default with ERROR, which shows up in featurekit_sdk_default_served_total.

Rename a flag without reshuffling

Set seed to a fixed integer and it replaces the flag key in the hash. The buckets then survive a rename. 0 is a valid seed.

Check before you widen

A dry run evaluates real contexts against the current and the proposed rollout and tells you who moves. A widening shows only additions. If many people move but the split barely changes, it warns you: that's a reshuffle, usually from a changed seed, key or variation order.

{ "sampled": 2000, "changed": 612, "reassigned": 0,
        "distributionBefore": { "true": 401, "false": 1599 },
        "distributionAfter":  { "true": 1013, "false": 987 } }

Measured on 200,000 synthetic users, a 10% rollout landed at 9.98%, and every decile fell between 9.5% and 10.5%.