-
Notifications
You must be signed in to change notification settings - Fork 44
docs: add desktop Feature Manifest reference, reorganize feature definition #795
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
1332ba5
docs: add desktop Feature Manifest reference, reorganize feature defi…
jaredlockhart 3996f7b
docs: address review feedback on feature manifest reference
jaredlockhart 18138bf
docs: restore original feature definition intro sentence
jaredlockhart 75fa50f
docs: restore inline YAML comments in feature-api example
jaredlockhart edc23d8
docs: restore original feature definition intro wording
jaredlockhart File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,228 @@ | ||
| --- | ||
| id: desktop-feature-manifest | ||
| title: Feature Manifest Reference | ||
| slug: /platform-guides/desktop/feature-manifest | ||
| --- | ||
|
|
||
| # Desktop Feature Manifest Reference | ||
|
|
||
| The desktop Nimbus Feature Manifest ([`FeatureManifest.yaml`](https://searchfox.org/mozilla-central/source/toolkit/components/nimbus/FeatureManifest.yaml)) defines every feature that can be configured by experiments and rollouts in Firefox Desktop. Each feature entry declares what variables it exposes, if those variables connect to Firefox prefs, and whether the feature supports exposure telemetry. | ||
|
|
||
| After adding or modifying a feature in the manifest, a build step is required to update the generated header file. | ||
|
|
||
| :::tip | ||
| This reference covers the **Desktop** manifest format (`FeatureManifest.yaml`). For mobile apps, see the [Feature Manifest Language (FML) specification](/technical-reference/fml/fml-spec). | ||
| ::: | ||
|
|
||
| ## Feature properties | ||
|
|
||
| Each top-level key in `FeatureManifest.yaml` is a feature ID. The feature definition supports these properties: | ||
|
|
||
| | Property | Required | Type | Default | Description | | ||
| | :--- | :---: | :--- | :--- | :--- | | ||
| | `description` | Yes | string | — | Human-readable description of the feature | | ||
| | `owner` | Yes | string | — | Email of the team or person responsible | | ||
| | `hasExposure` | Yes | boolean | — | Whether this feature records [exposure events](/data-analysis/jetstream/overview#enrollment-vs-exposure) | | ||
| | `exposureDescription` | If `hasExposure: true` | string | — | Describes when/how the exposure event fires | | ||
| | `variables` | Yes | object | — | Variable definitions (can be `{}` if the feature has no variables) | | ||
| | `isEarlyStartup` | No | boolean | `false` | Cache values in Firefox prefs for synchronous access during early startup | | ||
| | `allowCoenrollment` | No | boolean | `false` | Allow multiple simultaneous experiment/rollout enrollments for this feature | | ||
| | `applications` | No | string[] | `["firefox-desktop"]` | Which Firefox processes can enroll (see [Applications](#applications)) | | ||
| | `schema` | No | object | — | JSON Schema for validation (see [Schema validation](#schema-validation)) | | ||
|
|
||
| ### Applications | ||
|
|
||
| The `applications` array specifies which Firefox processes can use this feature: | ||
|
|
||
| - `"firefox-desktop"` — the main browser process (default) | ||
| - `"firefox-desktop-background-task"` — the background task runner | ||
|
|
||
| ```yaml | ||
| applications: | ||
| - firefox-desktop | ||
| - firefox-desktop-background-task | ||
| ``` | ||
|
|
||
| If omitted, defaults to `["firefox-desktop"]`. | ||
|
|
||
| ### Schema validation | ||
|
|
||
| The optional `schema` property points to a JSON Schema file that validates the combined feature configuration. It has two fields: | ||
|
|
||
| - `uri` — a `resource://` or `moz-src://` URI that Firefox loads at runtime for client-side validation | ||
| - `path` — a filesystem path (relative to the repository root) where Experimenter can find the schema | ||
|
|
||
| ```yaml | ||
| schema: | ||
| uri: resource://nimbus/schemas/PrefFlipsFeature.schema.json | ||
| path: toolkit/components/nimbus/schemas/PrefFlipsFeature.schema.json | ||
| ``` | ||
|
|
||
| ## Variable properties | ||
|
|
||
| Each key under `variables` defines a configurable variable. Variables support these properties: | ||
|
|
||
| | Property | Required | Type | Description | | ||
| | :--- | :---: | :--- | :--- | | ||
| | `description` | Yes | string | Human-readable description of the variable | | ||
| | `type` | Yes | string | One of `boolean`, `string`, `int`, `json` | | ||
| | `fallbackPref` | No | string | Pref to read the default value from (mutually exclusive with `setPref`) | | ||
| | `setPref` | No | string or object | Pref that Nimbus actively sets on enrollment (mutually exclusive with `fallbackPref`) | | ||
| | `enum` | No | array | Constrains allowed values (`string` and `int` types only) | | ||
|
|
||
| ### Variable types | ||
|
|
||
| | Type | Values | Supports `enum` | Notes | | ||
| | :--- | :--- | :---: | :--- | | ||
| | `boolean` | `true` / `false` | No | | | ||
| | `string` | Text values | Yes | | | ||
| | `int` | Whole numbers | Yes | | | ||
| | `json` | Arbitrary JSON objects/arrays | No | Stored as stringified JSON if connected to a pref | | ||
|
|
||
| :::note | ||
| There is no `float` type. If you need floating-point values, use `string` and parse the value in your code. | ||
| ::: | ||
|
|
||
| ### `fallbackPref` vs `setPref` | ||
|
|
||
| These are **mutually exclusive** — a variable can use one or the other, not both. | ||
|
|
||
| | | `fallbackPref` | `setPref` | | ||
| | :--- | :--- | :--- | | ||
| | **What it does** | Reads the current pref value as the default when no experiment is active | Nimbus actively **sets** the pref when the user enrolls | | ||
| | **On enrollment** | No change to the pref | Pref is set to the experiment branch value | | ||
| | **On unenrollment** | No change to the pref | Original pref value is restored | | ||
| | **If user changes pref** | No effect on enrollment | Causes automatic unenrollment | | ||
| | **Use case** | Feature gates and defaults that already exist as browser prefs | Controlling prefs that other code reads directly | | ||
|
|
||
| **`fallbackPref` example:** | ||
| ```yaml | ||
| enabled: | ||
| type: boolean | ||
| fallbackPref: browser.aboutwelcome.enabled | ||
| description: Whether the about:welcome page is enabled | ||
| ``` | ||
|
|
||
| **`setPref` example:** | ||
| ```yaml | ||
| enabled: | ||
| type: boolean | ||
| setPref: | ||
| branch: default # or "user" | ||
| pref: browser.search.visualSearch.featureGate | ||
| description: Feature gate for visual search | ||
| ``` | ||
|
|
||
| The `setPref` object format has two fields: | ||
| - `branch` — which pref branch to set: `"default"` (resets each startup) or `"user"` (persists to disk) | ||
| - `pref` — the pref name | ||
|
|
||
| :::note | ||
| For a deep dive into pref experiment behavior including unenrollment scenarios, pref branch trade-offs, and conflict handling, see [Pref Experiments](/platform-guides/desktop/pref-experiments). | ||
| ::: | ||
|
|
||
| ### `enum` constraints | ||
|
|
||
| The `enum` property restricts a `string` or `int` variable to a fixed set of values: | ||
|
|
||
| ```yaml | ||
| rankingMode: | ||
| type: string | ||
| enum: | ||
| - default | ||
| - interest | ||
| - random | ||
| description: The ranking algorithm to use | ||
| ``` | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Simple feature with a feature gate | ||
|
|
||
| ```yaml | ||
| search: | ||
| description: Search service related features | ||
| owner: search-and-suggest-program@mozilla.com | ||
| hasExposure: true | ||
| exposureDescription: > | ||
| Recorded when the visual search context menu item is shown. | ||
| variables: | ||
| visualSearchEnabled: | ||
| type: boolean | ||
| setPref: | ||
| branch: default | ||
| pref: browser.search.visualSearch.featureGate | ||
| description: Feature gate for visual search | ||
| ``` | ||
|
|
||
| ### Feature with multiple variable types | ||
|
|
||
| ```yaml | ||
| urlbar: | ||
| description: The Address Bar | ||
| owner: search-and-suggest-program@mozilla.com | ||
| hasExposure: true | ||
| exposureDescription: > | ||
| Recorded once per session on first urlbar interaction. | ||
| variables: | ||
| onboardingTimesToShow: | ||
| type: int | ||
| fallbackPref: browser.urlbar.quickactions.timesToShowOnboardingLabel | ||
| description: Number of times to show the onboarding label | ||
| quickSuggestRankingMode: | ||
| type: string | ||
| fallbackPref: browser.urlbar.quicksuggest.rankingMode | ||
| enum: | ||
| - default | ||
| - interest | ||
| - random | ||
| description: The ranking mode for QuickSuggest | ||
| scoreMap: | ||
| type: json | ||
| description: JSON object mapping result types to scores | ||
| ``` | ||
|
|
||
| ### Early startup feature | ||
|
|
||
| ```yaml | ||
| aboutwelcome: | ||
| description: The about:welcome page | ||
| owner: omc-core@mozilla.com | ||
| hasExposure: true | ||
| exposureDescription: > | ||
| Recorded once per session when about:welcome is shown. | ||
| isEarlyStartup: true | ||
| variables: | ||
| enabled: | ||
| type: boolean | ||
| fallbackPref: browser.aboutwelcome.enabled | ||
| description: Whether the about:welcome page is enabled | ||
| screens: | ||
| type: json | ||
| fallbackPref: browser.aboutwelcome.screens | ||
| description: Content to show in the onboarding flow | ||
| ``` | ||
|
|
||
| ### Co-enrolling feature | ||
|
|
||
| ```yaml | ||
| prefFlips: | ||
| description: Flip arbitrary prefs for incident response | ||
| owner: beth@mozilla.com | ||
| hasExposure: false | ||
| allowCoenrollment: true | ||
| variables: | ||
| prefs: | ||
| type: json | ||
| description: The prefs to set | ||
| schema: | ||
| uri: resource://nimbus/schemas/PrefFlipsFeature.schema.json | ||
| path: toolkit/components/nimbus/schemas/PrefFlipsFeature.schema.json | ||
| ``` | ||
|
|
||
| ## Further reading | ||
|
|
||
| - [Feature API Reference](/platform-guides/desktop/feature-api) — how to access feature values in code | ||
| - [Pref Experiments](/platform-guides/desktop/pref-experiments) — deep dive into `setPref` and `fallbackPref` behavior | ||
| - [Co-enrolling Features](/technical-reference/fml/coenrolling-features) — how `allowCoenrollment` works | ||
| - [FeatureManifest.yaml on Searchfox](https://searchfox.org/mozilla-central/source/toolkit/components/nimbus/FeatureManifest.yaml) — the live manifest | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.