1 files changed, 72 insertions, 0 deletions
diff --git a/toolkit/components/search/docs/SearchEngineConfiguration.rst b/toolkit/components/search/docs/SearchEngineConfiguration.rst
new file mode 100644
index 0000000000..c782f9f7c3
--- /dev/null
+++ b/toolkit/components/search/docs/SearchEngineConfiguration.rst
@@ -0,0 +1,72 @@
+===========================
+Search Engine Configuration
+===========================
+
+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 settings dumps to the Search Service is
+`the 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.
+
+An outline of the schema may be found on the `Search Configuration Schema`_ page.
+
+Updating Search Engine WebExtensions
+====================================
+
+Updates for application provided search engine WebExtensions are provided via
+`Normandy`_.
+
+It is likely that updates for search engine WebExtensions will be
+received separately to configuration updates which may or may not be directly
+related. As a result several situations may occur:
+
+    - The updated WebExtension is for an app-provided engine already in-use by
+      the user.
+
+      - In this case, the search service will apply the changes to the
+        app-provided engine's data.
+
+    - A WebExtension addition/update is for an app-provided engine that is not
+      in-use by the user, or not in the configuration.
+
+      - In this case, the search service will ignore the WebExtension.
+      - If the configuration (search or user) is updated later and the
+        new engine is added, then the Search Service will start to use the
+        new engine.
+
+    - A configuration update is received that needs a WebExtension that is
+      not found locally.
+
+      - In this case, the search service will ignore the missing engine and
+        continue without it.
+      - When the WebExtension is delivered, the search engine will then be
+        installed and added.
+
+.. _the remote settings: /services/settings/index.html
+.. _JSON schema: https://json-schema.org/
+.. _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-config/records
+.. _Normandy: /toolkit/components/normandy/normandy/services.html