preference-rollout: Permanently Change a Preference

The preference-rollout action permanently changes a preference in order to deploy a proven feature to most or all users of Firefox.

Users who match preference-rollout have values changed to match the configuration of the recipe. While the change is active, Telemetry pings are annotated to note that the rollout is changing a value to a non-default value. This allows us to measure the effect the preference change has on existing Telemetry metrics.

Preference rollout works by changing the value of the preferences on the default preference branch. Since changes to the default branch are not persistent, this process must be repeated every time Firefox starts. This process continues until a rollout is rolled back or until it graduates.

Rollouts do not support branching, and are intended to be permanent. If there is a mistake, a rollback can be undone with a preference-rollback action.

Note

Users may be enrolled in multiple preference rollouts at the same time.

Warning

Preference experiments are designed to be permanent. They are not appropriate for temporary changes.

Telemetry Annotation

While an experiment is running, the Telemetry Environment contains a list of “experiment” IDs. This field is also used to mark other non-default changes, such as rollouts. The Telemetry environment is sent along with the main ping, among others.

{
  "environment": {
    "experiments": {
      "<rollout id>": { "branch": "<branch>" },
    }
  }
}

Graduation

Rollouts expect that eventually the value of the preference built in to Firefox will change to match the value of the rollout. This generally happens when Firefox updates to a new version that has the preferences updated. When this happens, the preference rollout graduates. Once a rollout graduates, it stops setting the value of the preference at startup. If the default value then changes again, Normandy will not change it back to the rollout value.

Arguments

Slug

A unique identifier for this rollout. This is used for server and telemetry identification of the rollout.

Preferences

A list of preferences to change, each with the following arguments:

Name

The full dotted-path of the preference to modify.

Type

The type of the preference to modify. If this doesn’t match the type on the client, the rollout will not apply to anyone.

Value

Value to set the preference to for users that are assigned to this branch.