diff options
Diffstat (limited to 'toolkit/components/featuregates/docs/index.rst')
| -rw-r--r-- | toolkit/components/featuregates/docs/index.rst | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/toolkit/components/featuregates/docs/index.rst b/toolkit/components/featuregates/docs/index.rst new file mode 100644 index 0000000000..8a6f990de9 --- /dev/null +++ b/toolkit/components/featuregates/docs/index.rst @@ -0,0 +1,179 @@ +.. _components/featuregates: + +============= +Feature Gates +============= + +A feature gate is a high level tool to turn features on and off. It provides +metadata about features, a simple, opinionated API, and avoid many potential +pitfalls of other systems, such as using preferences directly. It is designed +to be compatible with tools that want to know and affect the state of +features in Firefox over time and in the wild. + +Feature Definitions +=================== + +All features must have a definition, specified in +``toolkit/components/featuregates/Features.toml``. These definitions include +data such as references to title and description strings (to be shown to users), +and bug numbers (to track the development of the feature over time). Here is an +example feature definition with an id of ``demo-feature``: + +.. code-block:: toml + + [demo-feature] + title = "experimental-features-demo-feature" + description = "experimental-features-demo-feature-description" + restart-required = false + bug-numbers = [1479127] + type = boolean + is-public = {default = false, nightly = true} + default-value = {default = false, nightly = true} + +The references defined in the `title` and `description` values point to strings +stored in ``toolkit/locales/en-US/toolkit/featuregates/features.ftl``. The `title` +string should specify the user-facing string as the `label` attribute. + +.. _targeted value: + +Targeted values +--------------- + +Several fields can take a value that indicates it varies by channel and OS. +These are known as *targeted values*. The simplest computed value is to +simply provide the value: + +.. code-block:: toml + + default-value: true + +A more interesting example is to make a feature default to true on Nightly, +but be disabled otherwise. That would look like this: + +.. code-block:: toml + + default-value: {default = false, nightly = true} + +Values can depend on multiple conditions. For example, to enable a feature +only on Nightly running on Windows: + +.. code-block:: toml + + default-value: {default = false, "nightly,win" = true} + +Multiple sets of conditions can be specified, however use caution here: if +multiple sets could match (except ``default``), the set chosen is undefined. +An example of safely using multiple conditions: + +.. code-block:: toml + + default-value: {default = false, nightly = true, "beta,win" = true} + +The ``default`` condition is required. It is used as a fallback in case no +more-specific case matches. The conditions allowed are + +* ``default`` +* ``release`` +* ``beta`` +* ``dev-edition`` +* ``nightly`` +* ``esr`` +* ``win`` +* ``mac`` +* ``linux`` +* ``android`` + +Fields +------ + +title + Required. The string ID of the human readable name for the feature, meant to be shown to + users. Should fit onto a single line. The actual string should be defined in + ``toolkit/locales/en-US/toolkit/featuregates/features.ftl`` with the user-facing value + defined as the `label` attribute of the string. + +description + Required. The string ID of the human readable description for the feature, meant to be shown to + users. Should be at most a paragraph. The actual string should be defined in + ``toolkit/locales/en-US/toolkit/featuregates/features.ftl``. + +description-links + Optional. A dictionary of key-value pairs that are referenced in the description. The key + name must appear in the description localization text as + <a data-l10n-name="key-name">. For example in Features.toml: + +.. code-block:: toml + + [demo-feature] + title = "experimental-features-demo-feature" + description = "experimental-features-demo-feature-description" + description-links = {exampleCom = "https://example.com", exampleOrg = "https://example.org"} + restart-required = false + bug-numbers = [1479127] + type = boolean + is-public = {default = false, nightly = true} + default-value = {default = false, nightly = true} + +and in features.ftl: + +.. code-block:: fluent + + experimental-features-demo-feature = + .label = Example Demo Feature + experimental-features-demo-feature-description = Example demo feature that can point to <a data-l10n-name="exampleCom">.com</a> links and <a data-l10n-name="exampleOrg">.org</a> links. + +bug-numbers + Required. A list of bug numbers related to this feature. This should + likely be the metabug for the the feature, but any related bugs can be + included. At least one bug is required. + +restart-required + Required. If this feature requires a the browser to be restarted for changes + to take effect, this field should be ``true``. Otherwise, the field should + be ``false``. Features should aspire to not require restarts and react to + changes to the preference dynamically. + +type + Required. The type of value this feature relates to. The only legal value is + ``boolean``, but more may be added in the future. + +preference + Optional. The preference used to track the feature. If a preference is not + provided, one will be automatically generated based on the feature ID. It is + not recommended to specify a preference directly, except to integrate with + older code. In the future, alternate storage mechanisms may be used if a + preference is not supplied. + +default-value + Optional. This is a `targeted value`_ describing + the value for the feature if no other changes have been made, such as in + a fresh profile. If not provided, the default for a boolean type feature + gate will be ``false`` for all profiles. + +is-public + Optional. This is a `targeted value`_ describing + on which branches this feature should be exposed to users. When a feature + is made public, it may show up in a future UI that allows users to opt-in + to experimental features. This is not related to ``about:preferences`` or + ``about:config``. If not provided, the default is to make a feature + private for all channels. + + +Feature Gate API +================ + +.. + (comment) The below lists should be kept in sync with the contents of the + classes they are documenting. An explicit list is used so that the + methods can be put in a particular order. + +.. js:autoclass:: FeatureGate + :members: addObserver, removeObserver, isEnabled, fromId + +.. js:autoclass:: FeatureGateImplementation + :members: id, title, description, type, bugNumbers, isPublic, defaultValue, restartRequired, preference, addObserver, removeObserver, removeAllObservers, getValue, isEnabled + + Feature implementors should use the methods :func:`fromId`, + :func:`addListener`, :func:`removeListener` and + :func:`removeAllListeners`. Additionally, metadata is available for UI and + analysis. |