Bug 1583214 - Split the search engine configuration schema documentation onto a separate page. r=mikedeboer
☠☠ backed out by 3123c2b245d3 ☠ ☠
authorMark Banner <standard8@mozilla.com>
Fri, 08 Nov 2019 12:04:00 +0000
changeset 501236 4eadc0b0b1f86fdf93f1647743d4558814466122
parent 501235 478c5bf5ccb37d3a38bda833a8751fd43db58ff1
child 501237 3d07be0ac7bc4299b733ab05d3d70c6a11cba14d
push id114168
push userdluca@mozilla.com
push dateSun, 10 Nov 2019 03:08:55 +0000
treeherdermozilla-inbound@33f64c1ef3e4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmikedeboer
bugs1583214
milestone72.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1583214 - Split the search engine configuration schema documentation onto a separate page. r=mikedeboer This helps with getting to the relevant parts more quickly, and a better heading scheme. Differential Revision: https://phabricator.services.mozilla.com/D52039
toolkit/components/search/docs/SearchConfigurationSchema.rst
toolkit/components/search/docs/SearchEngineConfiguration.rst
toolkit/components/search/docs/index.rst
copy from toolkit/components/search/docs/SearchEngineConfiguration.rst
copy to toolkit/components/search/docs/SearchConfigurationSchema.rst
--- a/toolkit/components/search/docs/SearchEngineConfiguration.rst
+++ b/toolkit/components/search/docs/SearchConfigurationSchema.rst
@@ -1,50 +1,23 @@
 ===========================
-Search Engine Configuration
+Search Configuration Schema
 ===========================
 
 .. note::
     This configuration is currently being implemented in `Bug 1542235`_.
 
-Configuration Management
-========================
-
-The application stores a dump of the configuration that is used for first
-initialisation. Subsequent updates to the configuration are either updates to the
-static dump, or they may be served via remote servers.
-
-The mechanism of delivering the dumps and settings to the Search Service is
-`Remote Settings`_
-
-Remote settings
----------------
-
-The remote settings bucket for the search engine configuration list is
-``search-config``. The version that is currently being delivered
-to clients can be `viewed live`_.
-
-Configuration Schema
-====================
-
-The configuration format is defined via a `JSON schema`_. The search engine
-configuration schema is `stored in mozilla-central`_ and is uploaded to the
-Remote Settings server at convenient times after it changes.
-
 This document outlines the details of the schema and how the various sub-parts
-interact. For the current fields and descriptions, please see the `schema itself`_.
-
-Configuration Structure
-=======================
+interact. For the full fields and descriptions, please see the `schema itself`_.
 
 .. note::
     In the examples, only relevant properties are displayed.
 
 Overview
---------
+========
 
 The configuration is a JSON blob which is object with a `data` property which
 is an array of engines:
 
 .. code-block:: js
 
     {
       data: [
@@ -53,17 +26,17 @@ is an array of engines:
         },
         {
           // engine 2 details
         }
       ]
     }
 
 Engine Objects
---------------
+==============
 
 An engine's details are located in the properties of the object associated with it.
 An engine that is deployed globally could be listed simply as:
 
 .. code-block:: js
 
     {
       "default": "no",
@@ -113,17 +86,17 @@ located specific regions or with certain
       }]
     }
 
 In this case users identified as being in the US region would use the WebExtension
 with identifier ``web-us@ext``, version 1.1. GB region users would get
 ``web-gb@ext`` version 1.2, and all other users would get ``web@ext`` version 1.0.
 
 Special Attributes
-------------------
+==================
 
 $USER_LOCALE
 ------------
 
 If a ``webExtension.locales`` property contains an element with the value
 ``"$USER_LOCALE"`` then the special value will be replaced in the
 configuration object with the users locale. For example:
 
@@ -151,17 +124,17 @@ depending on the user's locale.
 
 "default"
 ---------
 
 You can specify ``"default"`` as a region in the configuration if
 the engine is to be included when no region is specified.
 
 Experiments
------------
+===========
 
 We can run experiments by giving sections within ``appliesTo`` a
 ``cohort`` value, the Search Service can then optionally pass in a
 matching ``cohort`` value to match those sections.
 
 Sections which have a ``cohort`` will not be used unless a matching
 ``cohort`` has been passed in, for example:
 
@@ -187,17 +160,17 @@ Sections which have a ``cohort`` will no
         "webExtension": {
           "id": "web-gb@ext",
           "version": "1.2"
         }
       }]
     }
 
 Engine Defaults
----------------
+===============
 
 An engine may be specified as the default for one of two purposes:
 
 #. normal browsing mode,
 #. private browsing mode.
 
 If there is no engine specified for private browsing mode for a particular region/locale
 pair, then the normal mode engine is used.
@@ -273,17 +246,17 @@ In this example, for normal mode:
 In private browsing mode:
 
     - engine1@ext is default in the US region, and all other regions execpt for GB and FR
     - engine2@ext is default in only the GB region
     - engine3@ext is never default anywhere
     - engine4@ext is default in the FR region.
 
 Engine Ordering
----------------
+===============
 
 The ``orderHint`` field indicates the suggested ordering of an engine relative to
 other engines when displayed to the user, unless the user has customized their
 ordering.
 
 The default ordering of engines is based on a combination of if the engine is
 default, and the ``orderHint`` fields. The ordering is structured as follows:
 
@@ -318,17 +291,17 @@ Example:
       },
       "orderHint": 500,
       "default": "no"
     }
 
 This would result in the order: ``engine2@ext, engine1@ext, engine3@ext``.
 
 Engine Updates
---------------
+==============
 
 Within each engine definition is the extension id and version, for example:
 
 .. code-block:: js
 
   {
       "webExtension": {
         "id": "web@ext",
@@ -343,13 +316,9 @@ To locate an engine to use, the Search S
 
 If the WebExtension is listed in the ``attachment``, then the app will download
 to the user's profile, if it is not already there.
 
 If an application is downloading the WebExtension, or it is not available, then
 it may use an earlier version of the WebExtension until a new one becomes available.
 
 .. _Bug 1542235: https://bugzilla.mozilla.org/show_bug.cgi?id=1542235
-.. _Remote Settings: /services/common/services/RemoteSettings
-.. _JSON schema: https://json-schema.org/
-.. _stored in mozilla-central:
 .. _schema itself: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
-.. _viewed live: https://firefox.settings.services.mozilla.com/v1/buckets/main/collections/search-engine-configuration/records
--- a/toolkit/components/search/docs/SearchEngineConfiguration.rst
+++ b/toolkit/components/search/docs/SearchEngineConfiguration.rst
@@ -1,355 +1,43 @@
 ===========================
 Search Engine Configuration
 ===========================
 
 .. note::
     This configuration is currently being implemented in `Bug 1542235`_.
 
+The search engine configuration is a mapping that is used to determine the
+list of search engines for each user. The mapping is primarily based on the
+user's region and locale.
+
 Configuration Management
 ========================
 
 The application stores a dump of the configuration that is used for first
 initialisation. Subsequent updates to the configuration are either updates to the
 static dump, or they may be served via remote servers.
 
-The mechanism of delivering the dumps and settings to the Search Service is
+The mechanism of delivering the settings dumps to the Search Service is
 `Remote Settings`_
 
 Remote settings
 ---------------
 
 The remote settings bucket for the search engine configuration list is
 ``search-config``. The version that is currently being delivered
 to clients can be `viewed live`_.
 
 Configuration Schema
 ====================
 
 The configuration format is defined via a `JSON schema`_. The search engine
 configuration schema is `stored in mozilla-central`_ and is uploaded to the
 Remote Settings server at convenient times after it changes.
 
-This document outlines the details of the schema and how the various sub-parts
-interact. For the current fields and descriptions, please see the `schema itself`_.
-
-Configuration Structure
-=======================
-
-.. note::
-    In the examples, only relevant properties are displayed.
-
-Overview
---------
-
-The configuration is a JSON blob which is object with a `data` property which
-is an array of engines:
-
-.. code-block:: js
-
-    {
-      data: [
-        {
-          // engine 1 details
-        },
-        {
-          // engine 2 details
-        }
-      ]
-    }
-
-Engine Objects
---------------
-
-An engine's details are located in the properties of the object associated with it.
-An engine that is deployed globally could be listed simply as:
-
-.. code-block:: js
-
-    {
-      "default": "no",
-      "telemetryId": "engine1-telem",
-      "webExtension": {
-        "id": "web@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "everywhere": true
-        }
-      }]
-    }
-
-The ``appliesTo`` section is an array of objects. At least one object is required
-to specify which regions/locales the engine is included within. If an
-``appliesTo`` object lists additional attributes then these will override any
-attributes at the top-level.
-
-For example, a more complex engine definition may be available only to users
-located specific regions or with certain locales. For example:
-
-.. code-block:: js
-
-    {
-      "webExtension": {
-        "id": "web@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "region": "us"
-        },
-        "webExtension": {
-          "id": "web-us@ext",
-          "version": "1.1"
-        }
-      }, {
-        "included": {
-          "region": "gb"
-        },
-        "webExtension": {
-          "id": "web-gb@ext",
-          "version": "1.2"
-        }
-      }]
-    }
-
-In this case users identified as being in the US region would use the WebExtension
-with identifier ``web-us@ext``, version 1.1. GB region users would get
-``web-gb@ext`` version 1.2, and all other users would get ``web@ext`` version 1.0.
-
-Special Attributes
-------------------
-
-$USER_LOCALE
-------------
-
-If a ``webExtension.locales`` property contains an element with the value
-``"$USER_LOCALE"`` then the special value will be replaced in the
-configuration object with the users locale. For example:
-
-.. code-block:: js
-
-    {
-      "webExtension": {
-        "id": "web@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "locales": {
-            "matches": ["us", "gb"]
-          },
-          "webExtension": {
-            "locales": ["$USER_LOCALE"],
-          }
-        }
-      }]
-    }
-
-Will report either ``[us]`` or ``[gb]`` as the ``webExtension.locales``
-depending on the user's locale.
-
-"default"
----------
-
-You can specify ``"default"`` as a region in the configuration if
-the engine is to be included when no region is specified.
-
-Experiments
------------
-
-We can run experiments by giving sections within ``appliesTo`` a
-``cohort`` value, the Search Service can then optionally pass in a
-matching ``cohort`` value to match those sections.
-
-Sections which have a ``cohort`` will not be used unless a matching
-``cohort`` has been passed in, for example:
-
-.. code-block:: js
-
-    {
-      "webExtension": {
-        "id": "web@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "everywhere": true
-        },
-        "cohort": "nov-16",
-        "webExtension": {
-          "id": "web-experimental@ext"
-        }
-      }, {
-        "included": {
-          "everywhere": true
-        },
-        "webExtension": {
-          "id": "web-gb@ext",
-          "version": "1.2"
-        }
-      }]
-    }
-
-Engine Defaults
----------------
-
-An engine may be specified as the default for one of two purposes:
-
-#. normal browsing mode,
-#. private browsing mode.
-
-If there is no engine specified for private browsing mode for a particular region/locale
-pair, then the normal mode engine is used.
-
-If the instance of the application does not support a separate private browsing mode engine,
-then it will only use the normal mode engine.
-
-An engine may or may not be default for particular regions/locales. The ``default``
-property is a tri-state value with states of ``yes``, ``yes-if-no-other`` and
-``no``. Here's an example of how they apply:
-
-.. code-block:: js
-
-    {
-      "webExtension": {
-        "id": "engine1@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "region": "us"
-        },
-        "default": "yes"
-      }, {
-        "excluded": {
-          "region": "us"
-        },
-        "default": "yes-if-no-other"
-      }]
-    },
-    {
-      "webExtension": {
-        "id": "engine2@ext",
-        "version": "1.0"
-      },
-      "appliesTo": [{
-        "included": {
-          "region": "gb"
-        },
-        "default": "yes"
-      }]
-    },
-      "webExtension": {
-        "id": "engine3@ext",
-        "version": "1.0"
-      },
-      "default": "no"
-      "appliesTo": [{
-        "included": {
-          "everywhere": true
-        },
-      }]
-    },
-    {
-      "webExtension": {
-        "id": "engine4@ext",
-        "version": "1.0"
-      },
-      "defaultPrivate": "yes",
-      "appliesTo": [{
-        "included": {
-          "region": "fr"
-        }
-      }]
-    }
-
-In this example, for normal mode:
-
-    - engine1@ext is default in the US region, and all other regions except for GB
-    - engine2@ext is default in only the GB region
-    - engine3@ext and engine4 are never default anywhere
-
-In private browsing mode:
-
-    - engine1@ext is default in the US region, and all other regions execpt for GB and FR
-    - engine2@ext is default in only the GB region
-    - engine3@ext is never default anywhere
-    - engine4@ext is default in the FR region.
-
-Engine Ordering
----------------
-
-The ``orderHint`` field indicates the suggested ordering of an engine relative to
-other engines when displayed to the user, unless the user has customized their
-ordering.
-
-The default ordering of engines is based on a combination of if the engine is
-default, and the ``orderHint`` fields. The ordering is structured as follows:
-
-#. Default engine in normal mode
-#. Default engine in private browsing mode (if different from the normal mode engine)
-#. Other engines in order from the highest ``orderHint`` to the lowest.
-
-Example:
-
-.. code-block:: js
-
-    {
-      "webExtension": {
-        "id": "engine1@ext",
-        "version": "1.0"
-      },
-      "orderHint": 2000,
-      "default": "no",
-    },
-    {
-      "webExtension": {
-        "id": "engine2@ext",
-        "version": "1.0"
-      },
-      "orderHint": 1000,
-      "default": "yes"
-    },
-    {
-      "webExtension": {
-        "id": "engine3@ext",
-        "version": "1.0"
-      },
-      "orderHint": 500,
-      "default": "no"
-    }
-
-This would result in the order: ``engine2@ext, engine1@ext, engine3@ext``.
-
-Engine Updates
---------------
-
-Within each engine definition is the extension id and version, for example:
-
-.. code-block:: js
-
-  {
-      "webExtension": {
-        "id": "web@ext",
-        "version": "1.0"
-      },
-    }
-
-To locate an engine to use, the Search Service will look in the following locations (in order):
-
-#. within the user's install of the application.
-#. in the configuration to see if there is an ``attachment`` field.
-
-If the WebExtension is listed in the ``attachment``, then the app will download
-to the user's profile, if it is not already there.
-
-If an application is downloading the WebExtension, or it is not available, then
-it may use an earlier version of the WebExtension until a new one becomes available.
+An outline of the schema may be found on the `Search Configuration Schema`_ page.
 
 .. _Bug 1542235: https://bugzilla.mozilla.org/show_bug.cgi?id=1542235
 .. _Remote Settings: /services/common/services/RemoteSettings
 .. _JSON schema: https://json-schema.org/
-.. _stored in mozilla-central:
-.. _schema itself: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
+.. _stored in mozilla-central: https://searchfox.org/mozilla-central/source/toolkit/components/search/schema/
+.. _Search Configuration Schema: SearchConfigurationSchema.html
 .. _viewed live: https://firefox.settings.services.mozilla.com/v1/buckets/main/collections/search-engine-configuration/records
--- a/toolkit/components/search/docs/index.rst
+++ b/toolkit/components/search/docs/index.rst
@@ -3,8 +3,9 @@ Search Service
 ==============
 
 This is documentation for the Search Service.
 
 .. toctree::
    :maxdepth: 2
 
    SearchEngineConfiguration
+   SearchConfigurationSchema