mirror of
https://github.com/mozilla/gecko-dev.git
synced 2025-11-12 06:08:24 +02:00
59081613bd
Differential Revision: https://phabricator.services.mozilla.com/D5175 --HG-- extra : moz-landing-system : lando
147 lines
4.9 KiB
ReStructuredText
147 lines
4.9 KiB
ReStructuredText
.. _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.
|