Bug 1576507 - document FirstStartup module r=mythmon
☠☠ backed out by 2da8982d97aa ☠ ☠
authorRobert Helmer <rhelmer@mozilla.com>
Fri, 30 Aug 2019 23:21:03 +0000
changeset 490968 efca0164a7621c926a4661314d2120c67754ed0d
parent 490967 2238ba5cec98f76011ba7b53a019124b7d048e70
child 490969 9a0918622c83a226c6208ff7ea7a99df2d9a6bc2
push id114010
push userdluca@mozilla.com
push dateSat, 31 Aug 2019 09:58:00 +0000
treeherdermozilla-inbound@b3cc8963e871 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmythmon
bugs1576507
milestone70.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 1576507 - document FirstStartup module r=mythmon Differential Revision: https://phabricator.services.mozilla.com/D44035
toolkit/modules/docs/FirstStartup.rst
toolkit/modules/docs/index.rst
new file mode 100644
--- /dev/null
+++ b/toolkit/modules/docs/FirstStartup.rst
@@ -0,0 +1,74 @@
+.. _FirstStartup:
+
+==============
+FirstStartup
+==============
+
+``FirstStartup`` is a module which is invoked on application startup by the Windows Installer,
+to initialize services before the first application window appears.
+
+This is useful for:
+
+- one-time performance tuning
+- downloading critical data (hotfixes, experiments, etc)
+
+Blocking until the first Application window appears is important because the Installer
+will show a progress bar until this happens. This gives a user experience of:
+
+1. User downloads and starts the Windows Stub Installer.
+2. Progress bar advances while the application is downloaded and installed.
+3. Installer invokes the application with ``--first-startup``.
+4. Application window appears, and the installer window closes.
+
+Overall, the user experiences a very fast first-startup, with critical tasks that normally
+would be deferred until after UI startup already complete.
+
+.. _FirstStartup Architecture:
+
+FirstStartup: Example use case
+==============================
+
+An example use of the ``FirstStartup`` module is to invoke the Normandy client to download an experiment
+that will be used to customize the first-run page that Firefox shows.
+
+In this example, the first-run page would be loaded experimentally based on an attribution code provided
+by the Installer. The flow for this looks like:
+
+1. User clicks on download link containing an attribution (UTM) code(s).
+2. The download page serves a custom Windows Stub Installer with the appropriate attribution code embedded.
+3. The installer invokes Firefox with the `--first-startup` flag, which blocks the first window.
+4. Normandy is run by ``FirstStartup`` and downloads a list of available experiments, or "recipes".
+5. Recipes are evaluated and filtered based on local information, such as the OS platform and the attribution codes.
+6. A recipe is found which matches the current attribution code, and appropriate data is made available to the first-run page.
+7. ``FirstStartup`` completes and unblocks, which causes Firefox to show the first window and load the appropriate first-run data.
+
+List of phases
+==============
+
+``FirstStartup.NOT_STARTED``
+
+  The ``FirstStartup`` module has not been initalized (the ``init()``
+  function has not been called). This is the default state.
+
+``FirstStartup.IN_PROGRESS``
+
+  ``FirstStartup.init()`` has been called, and the event loop is
+  spinning. This state will persist until either all startup tasks
+  have finished, or time-out has been reached.
+
+  The time-out defaults to 5 seconds, but is configurable via the
+  ``first-startup.timeout`` pref, which is specified in milliseconds.
+
+``FirstStartup.TIMED_OUT``
+
+  The time-out has been reached before startup tasks are complete.
+
+  This status code is reported to Telemetry via the ``firstStartup.statusCode``
+  scalar.
+
+``FirstStartup.SUCCESS``
+
+  All startup tasks have completed successfully, and application startup may resume.
+
+  This status code is reported to Telemetry via the ``firstStartup.statusCode``
+  scalar.
--- a/toolkit/modules/docs/index.rst
+++ b/toolkit/modules/docs/index.rst
@@ -3,8 +3,9 @@ Toolkit Modules
 ===============
 
 The ``/toolkit/modules`` directory contains a number of self-contained toolkit modules considered small enough that they do not deserve individual directories.
 
 .. toctree::
   :maxdepth: 1
 
   AsyncShutdown
+  FirstStartup