summaryrefslogtreecommitdiffstats
path: root/toolkit/mozapps/extensions/docs
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--toolkit/mozapps/extensions/docs/AMRemoteSettings-JSONSchema.json56
-rw-r--r--toolkit/mozapps/extensions/docs/AMRemoteSettings-UISchema.json10
-rw-r--r--toolkit/mozapps/extensions/docs/AMRemoteSettings-overview.rst173
-rw-r--r--toolkit/mozapps/extensions/docs/AMRemoteSettings.rst5
-rw-r--r--toolkit/mozapps/extensions/docs/AddonManager.rst4
-rw-r--r--toolkit/mozapps/extensions/docs/SystemAddons.rst275
-rw-r--r--toolkit/mozapps/extensions/docs/index.rst21
7 files changed, 544 insertions, 0 deletions
diff --git a/toolkit/mozapps/extensions/docs/AMRemoteSettings-JSONSchema.json b/toolkit/mozapps/extensions/docs/AMRemoteSettings-JSONSchema.json
new file mode 100644
index 0000000000..46d15bc56e
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AMRemoteSettings-JSONSchema.json
@@ -0,0 +1,56 @@
+{
+ "type": "object",
+ "required": ["id"],
+ "properties": {
+ "id": {
+ "type": "string",
+ "default": "AddonManagerSettings",
+ "description": "The default id should NOT be changed, unless there is a specific need to create separate collection entries which target or exclude specific Firefox versions."
+ },
+ "installTriggerDeprecation": {
+ "$ref": "#/definitions/installTriggerDeprecation",
+ "optional": true
+ },
+ "quarantinedDomains": {
+ "$ref": "#/definitions/quarantinedDomains",
+ "optional": true
+ },
+ "filter_expression": {
+ "type": "string",
+ "description": "This is NOT directly used by AMRemoteSettings, but has special functionality in Remote Settings.\nSee https://remote-settings.readthedocs.io/en/latest/target-filters.html#how",
+ "optional": true
+ }
+ },
+ "definitions": {
+ "installTriggerDeprecation": {
+ "type": "object",
+ "properties": {
+ "extensions.InstallTrigger.enabled": {
+ "type": "boolean",
+ "default": false,
+ "description": "Show/Hide the InstallTrigger global completely (both the global and its methods will not be accessible anymore). IMPORTANT: The webcompat team should be consulted before turning this to false, because it may also potentially impact UA detection for some websites."
+ },
+ "extensions.InstallTriggerImpl.enabled": {
+ "type": "boolean",
+ "default": false,
+ "description": "Show/Hide the InstallTrigger methods. The InstallTrigger global will remain visible but set to null."
+ }
+ },
+ "description": "These settings control the visibility of the InstallTrigger global and its methods.",
+ "additionalProperties": false
+ },
+ "quarantinedDomains": {
+ "type": "object",
+ "properties": {
+ "extensions.quarantinedDomains.list": {
+ "type": "string",
+ "default": "",
+ "maxLength": 1048576,
+ "description": "Set of domains to be quarantined separated by a comma (e.g. 'domain1.org,domain2.com'). NOTE: this pref value should be set to a ASCII encoded string and its size smaller than 1MB"
+ }
+ },
+ "description": "These settings provide a set of domain names to be quarantined (restricted by default to unverified extensions, which only the app or the user may grant back). IMPORTANT: The add-ons team should be consulted before introducing any new entry of this type.",
+ "additionalProperties": false
+ }
+ }
+}
diff --git a/toolkit/mozapps/extensions/docs/AMRemoteSettings-UISchema.json b/toolkit/mozapps/extensions/docs/AMRemoteSettings-UISchema.json
new file mode 100644
index 0000000000..513449da92
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AMRemoteSettings-UISchema.json
@@ -0,0 +1,10 @@
+{
+ "installTriggerDeprecation": {
+ "extensions.InstallTrigger.enabled": {
+ "ui:widget": "radio"
+ },
+ "extensions.InstallTriggerImpl.enabled": {
+ "ui:widget": "radio"
+ }
+ }
+}
diff --git a/toolkit/mozapps/extensions/docs/AMRemoteSettings-overview.rst b/toolkit/mozapps/extensions/docs/AMRemoteSettings-overview.rst
new file mode 100644
index 0000000000..90a0445922
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AMRemoteSettings-overview.rst
@@ -0,0 +1,173 @@
+AMRemoteSettings Overview
+=========================
+
+``AMRemoteSettings`` is a singleton that is responsible for fetching data from a RemoteSettings collection named
+``"main/addons-manager-settings"`` to remotely control a set of Add-ons related preferences (hardcoded inside
+the AMRemoteSettings definition part of a given Firefox release).
+
+``AMRemoteSettings`` will process the collection data when the RemoteSettings ``"sync"`` event is fired and on
+late browser startup if there is already some data stored locally in the collection (and so if the pref value is
+manually changed, then it would be set again to the value stored in the RemoteSettings collection data, either
+on the next browser startup or on the next time the ``"sync"`` event is fired again).
+
+.. warning::
+ Any about:config preference that AMRemoteSettings singleton sets while processing the RemoteSettings collection data
+ are **never cleared automatically** (e.g. if in a future Firefox version AMRemoteSettings does not handle a particular
+ settings anymore, or if the RemoteSettings entry is removed from the collection on the RemoteSettings service side).
+
+ In practice this makes this feature a good choice when the remotely controlled about:config preferences is related to:
+
+ * Firefox Add-ons features in the process of being deprecated and then fully removed in a future Firefox release
+
+ * or controlled settings that are never removed from the ``"main/addons-manager-settings"`` collection.
+
+ In general before changing controlled settings in the ``"main/addons-manager-settings"`` collection it is advisable to:
+
+ * make sure to default value for the related about:config preferences has been changed in mozilla-central first,
+ and to let it ride the release train and get some backing time on release;
+
+ * only after that consider changing the value controlled by ``"main/addons-manager-settings"`` collection,
+ to set the same value on older Firefox releases where the previous default value was set.
+
+The ``AMRemoteSettings`` singleton queries RemoteSettings and processes all the entries got from the
+``"main/addons-manager-settings"`` collection, besides entries that may be filtered out by RemoteSettings based on
+the ``"filter_expression"`` property (See https://remote-settings.readthedocs.io/en/latest/target-filters.html#how).
+
+Each of the entries created in the ``"main/addons-manager-settings"`` collection and is expected to match the JSONSchema
+described in the :ref:`JSON Schema section below<JSON Schema>`.
+
+For each entry found in the collection, only the properties that are explicitly included in the
+``AMRemoteSettings.RS_ENTRIES_MAP`` object are going to be processed (e.g. new Firefox versions may have introduced new
+ones that older Firefox version will just ignore):
+
+* Each of the ``AMRemoteSettings.RS_ENTRIES_MAP`` properties:
+
+ * represents a group of settings (e.g. the property named ``"installTriggerDeprecation"``) is responsible of controlling
+ about:config preferences related to the InstallTrigger deprecation
+
+ * is set to an array of string, which lists the about:config preferences names that can actually be controlled by the
+ related group of settings (e.g. ``"installTriggerDeprecation"`` can only control two preferences,
+ ``"extensions.InstallTrigger.enabled"`` and ``"extensions.InstallTriggerImpl.enabled"``, that are controlling the
+ InstallTrigger and InstallTrigger's methods availability).
+
+.. warning::
+ Any other about:config preference names that are not listed explicitly in the ``AMRemoteSettings.RS_ENTRIES_MAP`` config
+ is expected to be ignored, even if allowed by a new version of the collection's JSONSchema (this is the expected behavior
+ and prevents the introduction of unexpected behaviors on older Firefox versions that may not be expecting new settings groups
+ that may be introduced in Firefox releases that followed it).
+
+ Any about:config preference with an unexpected value type is going to be ignored as well (look to the ``AMRemoteSettings.processEntries``
+ to confirm which preferences values types are already expected and handled accordingly).
+
+.. _Controlled Settings Groups:
+
+AMRemoteSettings - Controlled Settings Groups
+=============================================
+
+installTriggerDeprecation
+-------------------------
+
+Group of settings to control InstallTrigger deprecation (Bug 1754441)
+
+- **extensions.InstallTrigger.enabled** (boolean), controls the availability of the InstallTrigger global:
+
+ - Turning this to false will be hiding it completely
+
+ .. note::
+ Turning this off can potentially impact UA detection on website being using it to detect
+ Firefox. The WebCompat team should be consulted before setting this to `false` by default in
+ Nightly or across all Firefox >= 100 versions through the ``"addons-manager-settings"``
+ RemoteSettings collection).
+
+- **extensions.InstallTriggerImpl.enabled** (boolean): controls the availability of the InstallTrigger methods:
+
+ - Turning this to false will hide all the InstallTrigger implementation, preventing using it to
+ trigger the addon install flow, while the InstallTrigger global will still exists but be set to null.
+
+quarantinedDomains
+------------------
+
+Group of settings to control the list of quarantined domains (Bug 1832791)
+
+- **extensions.quarantinedDomains.list** (string), controls the list of domains to be quarantined
+
+ .. note::
+ The WebExtensions and Add-ons Operations teams should be consulted before applying changes to
+ the list of quarantined domains.
+
+How to define new remotely controlled settings
+----------------------------------------------
+
+.. note::
+ Please update the :ref:`JSON Schema` and :ref:`UI Schema` in this documentation page updated when the ones used on the
+ RemoteSettings service side have been changed, and document new controlled settings in the section :ref:`Controlled Settings Groups`.
+
+* Confirm that the :ref:`JSON Schema` and :ref:`UI Schema` included in this page are in sync with the one actually used on the
+ RemoteSettings service side, and use it as the starting point to update it to include a new type on remotely controlled setting:
+
+ * choose a new unique string for the group of settings to be used in the ``definitions`` and ``properties``
+ objects (any that isn't already used in the existing JSON Schema ``definitions``), possibly choosing a name
+ that helps to understand what the purpose of the entry.
+
+ * add a new JSONSchema for the new group of settings in the ``definitions`` property
+
+ * each of the properties included in the new definition should be named after the name of the about:config pref
+ being controlled, their types should match the type expected by the pref (e.g. ``"boolean"`` for a boolean preference).
+
+ * make sure to add a description property to the definition and to each of the controlled preferences, which should
+ describe what is the settings group controlling and what is the expected behavior on the values allowed.
+
+* Add a new entry to ``"AMRemoteSettings.RS_ENTRIES_MAP"`` with the choosen ``"id"`` as its key and
+ the array of the about:config preferences names are its value.
+
+* If the value type of a controlled preference isn't yet supported, the method ``AMRemoteSettings.processEntries`` has to be
+ updated to handle the new value type (otherwise the preference value will be just ignored).
+
+* Add a new test to cover the expected behaviors on the new remotely controlled settings, the following RemoteSettings
+ documentation page provides some useful pointers:
+ * https://firefox-source-docs.mozilla.org/services/settings/index.html#unit-tests
+
+* Refer to the RemoteSettings docs for more details about managing the JSONSchema for the ``"main/addons-manager-settings"``
+ collection and how to test it interactively in a Firefox instance:
+ * https://remote-settings.readthedocs.io/en/latest/getting-started.html
+ * https://firefox-source-docs.mozilla.org/services/settings/index.html#create-new-remote-settings
+ * https://firefox-source-docs.mozilla.org/services/settings/index.html#remote-settings-dev-tools
+
+.. _JSON Schema:
+
+AMRemoteSettings - JSON Schema
+==============================
+
+The entries part of the ``"addons-manager-settings"`` collection are validated using a JSON Schema structured as follows:
+
+* The mandatory ``"id"`` property
+ * defaults to `"AddonManagerSettings"` (which enforces only one entry in the collection as the preferred use case)
+ * **should NOT be changed unless there is a specific need to create separate collection entries which target or exclude specific Firefox versions.**
+ * when changed and multiple entries are created in this collection, it is advisable to:
+
+ * set the id to a short string value that make easier to understand the purpose of the additional entry in the collection
+ (eg. `AddonManagerSettings-fx98-99` for an entry created that targets Firefox 98 and 99)
+ * make sure only one applied to each targeted Firefox version ranges, or at least that each entry is controlling a different settings group
+
+* Each supported group of controlled settings is described by its own property (e.g. ``"installTriggerDeprecation"``)
+
+ * JSON Schema for each group of settings is defined in an entry of the ``"definitions"`` property.
+
+ * Each group of settings is contained it its own entry in ``"properties"``, named as the entry added to the ``"definitions"``)
+ and referencing (using ``"$ref"``) the related definition
+
+.. literalinclude :: ./AMRemoteSettings-JSONSchema.json
+ :language: json
+
+UI Schema
+---------
+
+In addition to the JSON Schema, a separate json called ``"UI schema"`` is associated to the ``"addons-manager-settings"`` collection,
+and it can be used to customize the form auto-generated based on the JSONSchema data.
+
+.. note::
+ Extending this schema is only needed if it can help to make the RemoteSettings collection easier to manage
+ and less error prone.
+
+.. literalinclude :: ./AMRemoteSettings-UISchema.json
+ :language: json
diff --git a/toolkit/mozapps/extensions/docs/AMRemoteSettings.rst b/toolkit/mozapps/extensions/docs/AMRemoteSettings.rst
new file mode 100644
index 0000000000..a555f426cc
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AMRemoteSettings.rst
@@ -0,0 +1,5 @@
+AMRemoteSettings Reference
+==========================
+
+.. js:autoclass:: AMRemoteSettings
+ :members:
diff --git a/toolkit/mozapps/extensions/docs/AddonManager.rst b/toolkit/mozapps/extensions/docs/AddonManager.rst
new file mode 100644
index 0000000000..9a5db82830
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AddonManager.rst
@@ -0,0 +1,4 @@
+AddonManager Reference
+======================
+.. js:autoclass:: AddonManager
+ :members:
diff --git a/toolkit/mozapps/extensions/docs/SystemAddons.rst b/toolkit/mozapps/extensions/docs/SystemAddons.rst
new file mode 100644
index 0000000000..a8524a44b6
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/SystemAddons.rst
@@ -0,0 +1,275 @@
+System Add-ons Overview
+=======================
+
+System add-ons are a method for shipping extensions to Firefox that:
+
+* are hidden from the about:addons UI
+* cannot be user disabled
+* can be updated restartlessly based on criteria Mozilla sets
+
+Generally these are considered to be built-in features to Firefox, and the
+fact that they are extensions and can be updated restartlessly are implementation
+details as far as users are concerned.
+
+If you'd like to ship an add-on with Firefox or as an update (either to an existing
+feature or as a "hotfix" to patch critical problems in the wild) please contact the
+GoFaster team: https://mail.mozilla.org/listinfo/gofaster
+
+The add-ons themselves are either legacy Firefox add-ons or WebExtensions.
+They must be:
+
+* restartless
+* multi-process compatible
+
+Other than these restrictions there is nothing special or different about
+the extensions themselves.
+
+It is possible to override an installed system add-on by installing a different add-on
+with the same ID into a higher priority location.
+
+Available locations, starting from the highest priority include:
+
+1) temporary install (about:debugging)
+2) normal user install into profile (about:addons or AMO/TestPilot/etc.)
+3) system add-on updates
+4) built-in system add-ons
+
+This makes it possible for a developer or user to override a system add-on
+by installing an add-on with the same ID from AMO or TestPilot or as a temporary
+add-on.
+
+Default, built-in system add-ons
+--------------------------------
+
+The set of **default** system add-ons are checked into `mozilla-central` under
+`./browser/extensions`. These get placed into the `features` directory of the
+application directory at build time.
+
+System add-on updates
+---------------------
+
+System add-on **updates** are served via Mozilla's Automatic Update Service
+(AUS, aka `Balrog`_). These are installed into the users profile under the `features`
+directory.
+
+Updates must be specifically signed by Mozilla - the signature that addons.mozilla.org
+uses will not work for system add-ons.
+
+As noted above, these updates may override a built-in system add-on, or they may
+be a new install. Updates are always served as a set - if any add-on in the set
+fails to install or upgrade, then the whole set fails. This is to leave Firefox
+in a consistent state.
+
+System add-on updates are removed when the Firefox application version changes,
+to avoid compatibility problems - for instance a user downgrading to an earlier
+version of Firefox than the update supports will end up with a disabled update
+rather than falling back to the built-in version.
+
+Firefox System Add-on Update Protocol
+=====================================
+This section describes the protocol that Firefox uses when retrieving updates
+from AUS, and the expected behavior of Firefox based on the updater service's response.
+
+.. _Balrog: https://wiki.mozilla.org/Balrog
+
+Update Request
+--------------
+To determine what updates to install, Firefox makes an HTTP **GET** request to
+AUS once a day via a URL of the form::
+
+ https://aus5.mozilla.org/update/3/SystemAddons/%VERSION%/%BUILD_ID%/%BUILD_TARGET%/%LOCALE%/%CHANNEL%/%OS_VERSION%/%DISTRIBUTION%/%DISTRIBUTION_VERSION%/update.xml
+
+The path segments surrounded by ``%`` symbols are variable fields that Firefox
+fills in with information about itself and the environment it's running in:
+
+``VERSION``
+ Firefox version number
+``BUILD_ID``
+ Build ID
+``BUILD_TARGET``
+ Build target
+``LOCALE``
+ Build locale
+``CHANNEL``
+ Update channel
+``OS_VERSION``
+ OS Version
+``DISTRIBUTION``
+ Firefox Distribution
+``DISTRIBUTION_VERSION``
+ Firefox Distribution version
+
+Update Response
+---------------
+AUS should respond with an XML document that looks something like this:
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <updates>
+ <addons>
+ <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ </addons>
+ </updates>
+
+* The root element is ``<updates>``, used for all updater responses.
+* The only child of ``<updates>`` is ``<addons>``, which represents a list of
+ system add-ons to update.
+* Within ``<addons>`` are several ``<addon>`` tags, each one corresponding to a
+ system add-on to update.
+
+``<addon>`` tags **must** have the following attributes:
+
+``id``
+ The extension ID
+``URL``
+ URL to a signed XPI of the specified add-on version to download
+``hashFunction``
+ Identifier of the hash function used to generate the hashValue attribute.
+``hashValue``
+ Hash of the XPI file linked from the URL attribute, calculated using the function specified in the hashValue attribute.
+``size``
+ Size (in bytes) of the XPI file linked from the URL attribute.
+``version``
+ Version number of the add-on
+
+Update Behavior
+---------------
+After receiving the update response, Firefox modifies the **update** add-ons
+according to the following algorithm:
+
+1. If the ``<addons>`` tag is empty (``<addons></addons>``) in the response,
+ **remove all system add-on updates**.
+2. If no add-ons were specified in the response (i.e. the ``<addons>`` tag
+ is not present), do nothing and finish.
+3. If the **update** add-on set is equal to the set of add-ons specified in the
+ update response, do nothing and finish.
+4. If the set of **default** add-ons is equal to the set of add-ons specified in
+ the update response, remove all the **update** add-ons and finish.
+5. Download each add-on specified in the update response and store them in the
+ "downloaded add-on set". A failed download **must** abort the entire system
+ add-on update.
+6. Validate the downloaded add-ons. The following **must** be true for all
+ downloaded add-ons, or the update process is aborted:
+
+ a. The ID and version of the downloaded add-on must match the specified ID or
+ version in the update response.
+ b. The hash provided in the update response must match the downloaded add-on
+ file.
+ c. The downloaded add-on file size must match the size given in the update
+ response.
+ d. The add-on must be compatible with Firefox (i.e. it must not be for a
+ different application, such as Thunderbird).
+ e. The add-on must be packed (i.e. be an XPI file).
+ f. The add-on must be restartless.
+ g. The add-on must be signed by the system add-on root certificate.
+
+6. Once all downloaded add-ons are validated, install them into the profile
+ directory as part of the **update** set.
+
+Notes on the update process:
+
+* Add-ons are considered "equal" if they have the same ID and version number.
+
+Examples
+--------
+The follow section describes common situations that we have or expect to run
+into and how the protocol described above handles them.
+
+For simplicity, unless otherwise specified, all examples assume that there are
+two system add-ons in existence: **FlyWeb** and **Pocket**.
+
+Basic
+~~~~~
+A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to
+update users to FlyWeb 2.0. AUS sends out the following update response:
+
+.. code-block:: xml
+
+ <updates>
+ <addons>
+ <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+ <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ </addons>
+ </updates>
+
+Firefox will download FlyWeb 2.0 and Pocket 1.0 and store them in the profile directory.
+
+Missing Add-on
+~~~~~~~~~~~~~~
+A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to
+update users to FlyWeb 2.0, but accidentally forget to specify Pocket in the
+update response. AUS sends out the following:
+
+.. code-block:: xml
+
+ <updates>
+ <addons>
+ <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+ </addons>
+ </updates>
+
+Firefox will download FlyWeb 2.0 and store it in the profile directory. Pocket
+1.0 from the **default** location will be used.
+
+Remove all system add-on updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A response from AUS with an empty add-on set will *remove all system add-on
+updates*:
+
+.. code-block:: xml
+
+ <updates>
+ <addons></addons>
+ </updates>
+
+Rollout
+~~~~~~~
+A user has Firefox 45, which shipped with FlyWeb 1.0 and Pocket 1.0. We want to
+rollout FlyWeb 2.0 at a 10% sample rate. 10% of the time, AUS sends out:
+
+.. code-block:: xml
+
+ <updates>
+ <addons>
+ <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+ <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ </addons>
+ </updates>
+
+With this response, Firefox will download Pocket 1.0 and FlyWeb 2.0 and install
+them into the profile directory.
+
+The other 90% of the time, AUS sends out an empty response:
+
+.. code-block:: xml
+
+ <updates></updates>
+
+With the empty response, Firefox will not make any changes. This means users who
+haven’t seen the 10% update response will stay on FlyWeb 1.0, and users who have
+seen it will stay on FlyWeb 2.0.
+
+Once we’re happy with the rollout and want to switch to 100%, AUS will send the
+10% update response to 100% of users, upgrading everyone to FlyWeb 2.0.
+
+Rollback
+~~~~~~~~
+This example continues from the “Rollout” example. If, during the 10% rollout,
+we find a major issue with FlyWeb 2.0, we want to roll all users back to FlyWeb 1.0.
+AUS sends out the following:
+
+.. code-block:: xml
+
+ <updates>
+ <addons>
+ <addon id="flyweb@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/flyweb/flyweb@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ <addon id="pocket@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/pocket/pocket@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+ </addons>
+ </updates>
+
+For users who have updated, Firefox will download FlyWeb 1.0 and Pocket 1.0 and
+install them into the profile directory. For users that haven’t yet updated,
+Firefox will see that the **default** add-on set matches the set in the update
+ping and clear the **update** add-on set.
diff --git a/toolkit/mozapps/extensions/docs/index.rst b/toolkit/mozapps/extensions/docs/index.rst
new file mode 100644
index 0000000000..551cdd0ebc
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/index.rst
@@ -0,0 +1,21 @@
+==============
+Add-on Manager
+==============
+
+Overview docs
+-------------
+
+.. toctree::
+ :maxdepth: 1
+
+ AMRemoteSettings-overview
+ SystemAddons
+
+API References
+--------------
+
+.. toctree::
+ :maxdepth: 1
+
+ AddonManager
+ AMRemoteSettings