Bug 1295732 - Update system add-on spec to reflect override behavior of updates. r=mkelly, a=NPOTB
authorRobert Helmer <rhelmer@mozilla.com>
Thu, 18 Aug 2016 18:33:08 -0700
changeset 347861 fa1adee0fb582bc6ae5542047d09b02a37e2a6f9
parent 347860 295ba38f59c87aa0ece0a187e403e71adcf5c9b7
child 347862 45689e52b2e6d1a0988cb3eeafe2b6e2f4654b38
push id6389
push userraliiev@mozilla.com
push dateMon, 19 Sep 2016 13:38:22 +0000
treeherdermozilla-beta@01d67bfe6c81 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmkelly, NPOTB
bugs1295732
milestone50.0a2
Bug 1295732 - Update system add-on spec to reflect override behavior of updates. r=mkelly, a=NPOTB MozReview-Commit-ID: GNSMwBxFN2Z
toolkit/mozapps/extensions/docs/SystemAddons.rst
--- a/toolkit/mozapps/extensions/docs/SystemAddons.rst
+++ b/toolkit/mozapps/extensions/docs/SystemAddons.rst
@@ -5,17 +5,18 @@ for System Add-ons from the automatic up
 and the expected behavior of Firefox based on the updater service's response.
 
 .. _Balrog: https://wiki.mozilla.org/Balrog
 
 System Add-ons
 --------------
 System add-ons:
 
-* Are add-ons that ship with Firefox and cannot be disabled
+* Are add-ons that ship with Firefox, are hidden from the UI, and cannot be
+  disabled
 * Can be updated by Firefox depending on the AUS response to Firefox's update
   request
 * Are stored in two locations:
 
   * The **default** set ships with Firefox and is stored in the application
     directory.
   * The **update** set is stored in the user’s profile directory. If an add-on
     is both in the update and default set, the update version gets precedence.
@@ -51,17 +52,17 @@ 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="loop@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/hello/loop@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+      <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
@@ -83,18 +84,17 @@ AUS should respond with an XML document 
   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,
-   **disable all system add-ons**, including both the **update** and **default**
-   sets.
+   **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
@@ -111,130 +111,114 @@ 6. Validate the downloaded add-ons. The 
    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.
-7. Disable any **default** add-ons that were not present in the update response.
 
 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: **Loop** and **Pocket**.
+two system add-ons in existence: **FlyWeb** and **Pocket**.
 
 Basic
 ~~~~~
-A user has Firefox 45, which shipped with Loop 1.0 and Pocket 1.0. We want to
-update users to Loop 2.0. AUS sends out the following update response:
+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="loop@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/hello/loop@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+      <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 Loop 2.0 and Pocket 1.0 and store them in the profile directory.
+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 Loop 1.0 and Pocket 1.0. We want to
-update users to Loop 2.0, but accidentally forget to specify Pocket in the
+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="loop@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/hello/loop@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+      <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 Loop 2.0 and store it in the profile directory. It will
-disable Pocket completely.
+Firefox will download FlyWeb 2.0 and store it in the profile directory. Pocket
+1.0 from the **default** location will be used.
 
-Disable all system add-ons
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-A response from AUS with an empty add-on set will *disable all system add-ons*:
+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 Loop 1.0 and Pocket 1.0. We want to
-rollout Loop 2.0 at a 10% sample rate. 10% of the time, AUS sends out:
+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="loop@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/hello/loop@mozilla.org-2.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="2.0"/>
+      <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 Loop 2.0 and install
+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 Loop 1.0, and users who have
-seen it will stay on Loop 2.0.
+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 Loop 2.0.
+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 Loop 2.0, we want to roll all users back to Loop 1.0.
+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="loop@mozilla.org" URL="https://ftp.mozilla.org/pub/system-addons/hello/loop@mozilla.org-1.0.xpi" hashFunction="sha512" hashValue="abcdef123" size="1234" version="1.0"/>
+      <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 Loop 1.0 and Pocket 1.0 and
+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.
-
-Disable an Add-on
-~~~~~~~~~~~~~~~~~
-A user has Firefox 45, with Pocket 1.0 and Loop 1.0. Loop 1.0 ends up having a
-serious bug, and we want to disable the add-on completely while we work on a
-fix. AUS sends out the following:
-
-.. code-block:: xml
-
-  <updates>
-    <addons>
-      <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 Pocket 1.0 and install it to the profile directory, and disable Loop.