Rolling Out a Feature Flag: Rollouts, Plans and Schedules

The Rollout tab of a flag holds everything about how much of your traffic gets On and how that changes over time: the rollout itself, the rollout plan, the holdback and the schedule.

The rollout

The rollout is the share of visitors who get On, from 0% to 100%. Set it by hand with the slider or the number next to it, then Save, or Discard to go back. The figure updates as you drag.

Raising the rollout only adds people. Every visitor has a fixed bucket for each flag, so someone who has On keeps it as the share grows, and nobody flips back and forth between the two sides. Visitors move from On to Off only when you lower the rollout or turn the flag off, when they leave the flag's targeting, or when they join a ring that serves Off.

Saving a rollout by hand pauses a running plan. The card says so before you save: "Saving pauses the running plan."

The rollout plan

A plan is a list of steps the rollout moves through on its own, so you can go from a small share to everyone without coming back to the page each time. Without a plan, the card says "No plan: the rollout changes only by hand."

A plan has up to 10 steps. Each step sets:

• Rollout %: the share who get On while the step is current. Each step must be at least the one before it. A plan only widens the rollout, and saving a plan that narrows it is refused: "Step n rolls out less than step n-1; a plan only widens the rollout".
• Stay at least: how long the step lasts before the plan may move on, in hours or days, up to a year.
• Not before: an optional date the plan waits for before moving on.
• Moves on after: Time, Guardrail, or Time and guardrail. Time moves on once the step has stayed its least time and its date has passed. Guardrail moves on once the guardrail has checked that On does no worse than Off. Time and guardrail waits for both. See Feature Flag Guardrails.

On a draft, the plan starts at its first step when you publish. On a live flag, Start plan starts it, Pause holds the rollout where it is, and Resume continues.

Starting or resuming never narrows the rollout. The plan picks up at the first step whose share is at or above the current rollout, and the confirmation says what will happen: "The rollout goes from x to y at once", or "stays at x", and "That step's least time counts from now". If the rollout is already past every step, the plan is marked done and the rollout stays where it is.

Steps can only be edited while the plan is paused or has not started. On a running plan the editor is locked, with the note "Pause the plan to change its steps."

Holdback

A holdback is a share kept Off at every step, even at 100%, so there is always a group to compare with. It can be anything from 0 to 50%, and it can only be set before the flag is published.

With a holdback of 5%, at most 95% of visitors can get On, and the card says so: "The holdback keeps 5% Off, so at most 95% get On." Holdback visitors count as Off when the guardrail compares the two sides.

Schedule

The Schedule card publishes or turns off at a set time.

• Publish at, on a draft, publishes the flag at that time. If it has a plan, the plan starts then.
• Turn off at, on a live flag, sends everyone to Off at that time. It also pauses a running plan, in the same way a turn off by hand does.

Both times have to be in the future, and a turn off has to come after the publish. A draft whose turn-off time has already passed cannot be published until you clear or move it.

The scheduler runs every minute, so a scheduled change happens within a minute of its time. Changes the scheduler makes are recorded on the Activity tab without a name, and each one sends a notification if you have it switched on. See Notifications in Pertento.

What the statuses mean

The Library shows one status per flag:

• Draft: not published. Nothing reaches visitors.
• Rolling out: a plan is running. This status wins over the share the flag is at.
• Paused: a plan is paused, by hand or by the guardrail, and the share is above 0%.
• Partly on: live and held at a share by hand, with no plan moving it.
• Fully on: live at 100%.
• Off: live, but at 0%. Nobody gets On until the rollout is raised.
• Archived: retired. Everyone gets Off, and the flag cannot be turned on again.

The Next step column says what comes next: "Starts at n%" for a draft, "Waiting for you" for a paused plan, "Guardrail breach" when the guardrail paused it, "Last step" when the plan is on its final step, or when the next step is due.

On the flag's own page, the status card under the name says the same in more detail: Draft, Live or Archived, how many percent get On, the plan's state ("Not started", "Step n of N", "Paused at step n of N" or "Done"), and what comes next: "Publishes" or "Turns off" with the date, "Waiting for you", "Nothing scheduled" or "Everyone gets Off".