Skip to main content

Working with Feature Manifests

The Feature Manifest Language is a powerful way of specify the shape of the feature configurations that each branch is made up of.

The nimbus-cli knows about the feature manifests for each of the apps, and can validate experiments before they launch.

validate​

nimbus-cli --app firefox_ios --channel release validate ios-sync-manager-integration

This downloads the feature manifest (the fml file), and checks each of the features in each of the branches.

✅ Loaded manifest from https://raw.githubusercontent.com/mozilla-mobile/firefox-ios/main/nimbus.fml.yaml
✅ control           rust-sync-manager-component
✅ rust-sync-manager rust-sync-manager-component

By default, this will download the version from main, however you can specify a version of the FML.

nimbus-cli --app firefox_ios --channel release validate preview/release-ios-re-engagement-notifications-ab-experiment-114 --version 114

Using the --version parameter, we can specify 114 which for firefox_ios, this currently translates to the release/v114 tag.

✅ Loaded manifest from https://raw.githubusercontent.com/mozilla-mobile/firefox-ios/release/v114/nimbus.fml.yaml
✅ control         messaging
✅ treatment-a     messaging
✅ treatment-b     messaging
✅ treatment-c     messaging

Using the --ref parameter, we can a tag, a different branch or a commit hash.

Alternatively, we can specify a local manifest file.

nimbus-cli --app firefox_ios --channel release validate preview/release-ios-re-engagement-notifications-ab-experiment-114 --manifest ./my-manifest.fml.yaml

defaults​

The defaults commands outputs the default configuration, for all features of the app configured by Nimbus.

An optional --feature parameter can be specified to only output the default configuration for that particular feature.

For example,

nimbus-cli --app firefox_ios --channel release defaults --feature homescreenFeature

currently outputs the following JSON:

{
  "jump-back-in-synced-tab": true,
  "pocket-sponsored-stories": false,
  "sections-enabled": {
    "jump-back-in": true,
    "pocket": true,
    "recent-explorations": true,
    "recently-saved": true,
    "top-sites": true
  },
  "sponsored-tiles": {
    "max-number-of-tiles": 2,
    "status": true
  }
}

features​

A manifest can be used to change the behavior of the features command.

If the --validate flag is set, then the branch feature configuration is merged with the defaults from the manifest.

For example, without --validate, the command:

nimbus-cli --app firefox_ios --channel developer features ios-search-bar-placement-v2-treatment-a-rollout --branch treatment-a

outputs the following JSON, extracted from the experiment:

{
  "awesome-bar": {
    "position": {
      "is-bottom": false,
    }
  }
}

Using --validate, the defaults from the feature manifest are also shown: this gives an accurate picture of the complete configuration that the app will use for this feature.

nimbus-cli --app firefox_ios --channel developer features ios-search-bar-placement-v2-treatment-a-rollout --branch treatment-a --validate

Gives the above output merged with the defaults from the manifest:

{
  "awesome-bar": {
    "position": {
      "is-bottom": false,
      "is-position-feature-enabled": true,
      "is-toolbar-cfr-on": false
    },
    "search-highlights": false,
    "use-page-content": false
  }
}

Other commands​

By default, the enroll and test-feature validates the experiments before sending them to the device.

This can be overridden with the --no-validate option.

enroll​

nimbus-cli --app firefox_ios --channel release enroll ios-sync-manager-integration --branch rust-sync-manager

The manifest itself is validated on load, so if there is a problem with that feature, you can skip validation with --no-validate.

nimbus-cli --app firefox_ios --channel developer enroll ios-set-to-default-in-onboarding-final --branch control --no-validate

Each of the --manifest, --version and --ref options work with enroll, test-feature, features and defaults.

Working with the nimbus-fml command line​

The Feature Manifest Language has its own command line interface. This can be used to validate manifest files, generate code, and rationalize manifests in to a single file.

For example:

nimbus-cli fml validate @mozilla/blurts-server/config/nimbus.yaml

The documentation there is better placed to explain how to use it, however there is one caveat: flags (i.e. modifiers that begin with --) are caught by the nimbus-cli command line, rather than passed to the nimbus-fml command line.

Thus, you should use -- before their first use. For example:

nimbus-cli fml -- --help

will display the nimbus-fml help message.

You can put the -- anywhere before the first modifier: the following two commands are equivalent.

nimbus-cli fml -- generate-experimenter --channel release @mozilla/blurts-server/config/nimbus.yaml blurts.experimenter.yaml

and

nimbus-cli fml generate-experimenter @mozilla/blurts-server/config/nimbus.yaml blurts.experimenter.yaml -- --channel release