.. _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.