Software Update:Testing

From MozillaWiki
Jump to: navigation, search


Input Parameters:

  • Update Service URL
  • Update Service XML File
  • Partial Update Patch
  • Complete Update Patch
  • Update Settings
  • UI Features
  • Workflows

1. Update Service URL:

 - set app.update.url.override to use a custom update service XML file which 
   may be deployed on your box. 
 - test for DNS failure, 404, etc. 

2. Update Service XML File:

 - Formatted like so:
   <?xml version="1.0"?>
   <updates xmlns="">
     <update type="minor"
       <patch type="partial"
       <patch type="complete"
 - <update type="minor|major" ..> 
   implies security vs. major update, and text in the Update Wizard differs 
   depending on what is supplied.
 - <update version="1.1.2" ..> 
   is the version of the update
 - <update extensionVersion="1.1" ..> 
   is the general application version targeted by extensions that are
   compatible with this update (used for compatibility checking)
 - <update detailsURL=".." ..>
   is the URL where users can find more information about what's new in this
   update. This should be user friendly, concise, and not the full release
   notes page, although it could be a subset of a multi-page release notes
   information set.
 - <update licenseURL=".." ..>
   is the URL where a HTML fragment containing a new license that must be 
   accepted by the user before they can install this update is stored. If
   this is not supplied, then the user is not shown the license UI.
 - <patch URL=".." ..>
   is the the URL where the update .mar file can be found
 - <patch type="partial|complete" ..>
   is the type of patch - partial for a binary difference patch, complete for
   a complete set of replacement files.
 - <patch size="234234" ..>
   is the size (in bytes) of the update .mar file. This is currently unused
   but should be supplied.
 - <patch hashFunction="sha256" ..>
   Hash function names are stored here:
   Test invalid values for hash function name
 - <patch hashValue=".." ..>
   Hash function value is computed by the build system to prevent tampering
   with files by hacked mirrors and to make sure we don't try and apply a 
   patch file that was corrupted during the download process. Test valid
   and invalid hash values. 
   Invalid values for partial patches should cause the update system to 
   begin downloading the complete patch instead. If the user is monitoring
   the download process they will be informed fo the failure by the UI.
 - There can be more than one <update> entries in a single XML file, the 
   Update Service client should select the newest.

3. Partial Update File

 - the binary difference of two versions of the application. See darin's notes
   for information on generating

4. Complete Update File

 - the complete set of files and update commands required to install a working
   instance of the application. Should be completely autonomous. See darin's
   notes for information on generating.  

5. Update Settings

 - There are several preferences which control the Update Service client:
 BOOLEAN - app.update.enabled              Default: true
   enables or disables the background update checker. UI is still available
   for the user to manually check for updates (in Options or the Help menu), 
   this UI should also be disabled when this preference is locked by an
 BOOLEAN -                 Default: true
   enables background download of update .mar files, according to the 
   policy described by app.update.mode
 INTEGER - app.update.mode                 Default: 1
   defines the policy by which background downloads are done, and the amount
   of user prompting that is required:
   0 - download all update types (major/minor) without user intervention,
       regardless of incompatible extensions installed (they should just be
       disabled after the update restart)
   1 - download all update types (major/minor) only if there are no 
       incompatibilities with enabled extensions, prompt with UI otherwise.
   2 - download minor updates only, prompt for major updates, regardless
       of whether or not all enabled extensions are compatible.
 Note: The following applies to Gecko 1.9.1 / Firefox 3.5 and below
 BOOLEAN - app.update.log.*                Default: false
   enables logging for various Update Service components, set preferences
   like so:
     app.update.log.ModuleName = true
     Checker, Downloader, UpdateService, General, UpdateManager, 
     UI:DownloadingPage, UI:CheckingPage, UI:LicensePage, etc. 
 Note: The following applies to Gecko 1.9.2 / Firefox 3.6 and above
 BOOLEAN - app.update.log                  Default: false
   enables logging for the Application Update Service components
 WSTRING - app.update.url.manual           Default: <url>
   the default update service XML file URL
 WSTRING - app.update.url.override         Default: ""
   an override value for the update service XML file URL for testing
 INTEGER - app.update.timer                Default: 5000
   the number of milliseconds between checker update interval expiry checks
   NOTE: this is NOT the time between service URL pings!
 INTEGER - app.update.interval             Default: 86400
   the number of seconds between service XML pings. expiry of this interval
   is checked with a separate timer determined by |app.update.timer|
 INTEGER -    Default: 86400
   the number of seconds after a user chooses the "Later" button in the
   update available nag UI to wait before annoying them with news of the
   update again.
 INTEGER - app.update.nagTimer.restart     Default: 1800
   the number of seconds after the user chooses to Restart the browser 
   Later after an update has been downloaded to annoy them with a prompt
   to restart.
 BOOLEAN - app.update.silent               Default: false
   disables all notification UI for updates, does not mean that the updates
   will not occur though - they will according to the other control
   preferences, just without prompting the user.
 BOOLEAN - app.update.showInstalledUI      Default: false
   disables the "Update was Successfully Installed" page for Firefox only, 
   since Firefox uses a start page to inform the user that they have upgraded,
   Thunderbird and other non-browser apps will set this to true.

6. UI Features

  - Update Wizard UI
    (Help, Check for Updates...)
    (Tools, Options, Advanced, Update, Check Now...)
    (<background invocation>)
  - Update History UI
    (Tools, Options, Advanced, Update, Show Update History...)
  - Update Preferences
    (Tools, Options, Advanced, Update)

6. Workflows

   Background Checker:
     - if background checking is enabled, the application will periodically
       check for updates and if it finds them take action depending on the
       value of and app.update.mode (see above).
     - if a partial patch fails to verify, the service will begin downloading
       a complete update. If the complete update fails to verify, then the
       service will either die silently (in the background) and will check
       again in another 24 hours, or will notify the user of this failure
       (in the foreground) and provide a link that the user can follow to
       manually update their software immediately.
     - once a patch has been downloaded and verified, the user will be 
       notified of this and prompted to restart the browser (they can opt out)
       - this prompting is done regardless of whether or not the update 
       download was done in the background or if the user gave consent or not.
     - the application is restarted either by the prompt UI or later, manually
       by the user, and the patch application process is initiated. 
     - if a partial patch fails to apply, the service will notify the user
       about this and tell them it will download a complete patch. It will
       present a UI to track the download. The user is free to browse while
       this download occurs. When the download is complete they are prompted
       to restart again. 
     - if a complete patch fails to apply, they are shown a URL that they can
       navigate to to manually update their software.
   Foreground Checker:
     - works the same way, except there is a UI present on screen for each
       stage of the process. some heuristics relating to user notification
       and the content of each stage of the wizard vary depending on whether
       or not the system was invoked by the user or the background checker.

Extension Update Across Major Updates

To test Extension Update across major application updates with a nightly build, you need:

  • some extensions (installed)
  • preferably some test extensions that you can hand edit

Open the file compatibility.ini in your profile and change the line that reads something like:


to have a number different than the one shown, e.g.:


Now, open prefs.js in your profile and:


user_pref("app.extensions.version", "5.0");

(or some other number much larger than the current version)

and make sure there is no line like this:

user_pref("extensions.lastVersion", "5.0"); or similar.

Now start Firefox. A wizard UI should appear and allow you to check for updates to your incompatible extensions.


When the Firefox starts, it detects the update condition that you created by editing the files as described above. It collects a list of addons that are incompatible with the new running instance, and then:

  • checks for VersionInfo updates to each of the items in the list... a VersionInfo update is a remove compatibility update provided by the author of the addon through AMO or their custom update.rdf file that says that the existing installed version of the addon is in fact compatible with the new version of Firefox, and requires no new XPI download/install
  • after the VersionInfo check reduces the incompatibility list somewhat, displays a list of addons that are still incompatible and will need to be updated to still be functional.
  • checks for newer versions of the said addons.
  • when it discovers the updates that are available, shows them to the user and gives them the ability to download and install them now.
  • downloads and installs the selected updates
  • shows information to the user about any errors encountered in this process, also, shows information about items that are still incompatible (no updates found), and gives the user the ability to opt into auto update checking if the user has previously disabled extension auto update checking.