summaryrefslogtreecommitdiffstats
path: root/toolkit/components/featuregates/docs/index.rst
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/featuregates/docs/index.rst')
-rw-r--r--toolkit/components/featuregates/docs/index.rst179
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.