toolkit/components/featuregates/docs/index.rst
author Mike Cooper <mcooper@mozilla.com>
Wed, 09 Jan 2019 16:15:59 +0000
changeset 510226 7e107869b00d7ccc5051809d6839be6e98cc4165
permissions -rw-r--r--
Bug 1479127 - Add featuregate library r=mossop,firefox-build-system-reviewers,mshal Differential Revision: https://phabricator.services.mozilla.com/D5175

.. _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 title and description (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 = "Demo Feature"
   description = "A no-op feature to demo the feature gate system."
   restart-required = false
   bug-numbers = [1479127]
   type = boolean
   is-public = {default = false, nightly = true}
   default-value = {default = false, nightly = true}

.. _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. A human readable name for the feature, meant to be shown to
    users. Should fit onto a single line.

description
    Required. A human readable description for the feature, meant to be shown to
    users. Should be at most a paragraph.

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.