Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 315 insertions, 0 deletions

diff --git a/browser/docs/BrowserUsageTelemetry.rst b/browser/docs/BrowserUsageTelemetry.rst
new file mode 100644
index 0000000000..e343830833
--- /dev/null
+++ b/browser/docs/BrowserUsageTelemetry.rst
@@ -0,0 +1,148 @@
+.. _browserusagetelemetry:
+
+=======================
+Browser Usage Telemetry
+=======================
+
+The `BrowserUsageTelemetry.jsm <https://searchfox.org/mozilla-central/source/browser/modules/BrowserUsageTelemetry.jsm>`_ module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...).
+
+The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts).
+
+Tab and window interactions
+===========================
+The usage telemetry module currently measures these interactions with the browser's tabs and windows:
+
+- *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``);
+- *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``);
+- *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``).
+
+
+Please see `Scalars.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ for the full list of tracked interactions.
+
+Customizable UI
+===============
+
+This telemetry records information about the positions of toolbar items and when
+the user interacts with them. It is submitted as scalar values along with the
+normal telemetry ping. There are a number of different parts to this telemetry:
+
+UI Areas
+--------
+
+For the purposes of this telemetry a set of areas are defined:
+
+* In the main browser UI:
+
+  * ``menu-bar`` - The main menu.
+  * ``menu-toolbar`` - The normally hidden toolbar that holds the main menu.
+  * ``titlebar`` - The optional title bar.
+  * ``tabs-bar`` - The area where tabs are displayed.
+  * ``bookmarks-bar`` - The bookmarks toolbar.
+  * ``app-menu`` - The main application (hamburger) menu.
+  * ``tabs-context`` - The context menu shown from right-clicking a tab.
+  * ``content-context`` - The context menu shown from right-clicking the web page.
+  * ``widget-overflow-list`` - Items that have overflowed the available space.
+  * ``pinned-overflow-menu`` - Items that the user has pinned to the toolbar overflow menu.
+  * ``pageaction-urlbar`` - Page actions buttons in the address bar.
+  * ``pageaction-panel`` - The page action (meatball) menu.
+  * ``nav-bar-start`` - The area of the navigation toolbar before the address bar.
+  * ``nav-bar-end`` - The area of the navigastion toolbar after the address bar.
+  * ``unified-extensions-area`` - The unified extensions panel.
+
+* In ``about:preferences`` the different cagtegories are used:
+
+  * ``preferences-paneGeneral``
+  * ``preferences-paneHome``
+  * ``preferences-panePrivacy``
+  * ``preferences-paneSearch``
+  * ``preferences-paneSearchResults``
+  * ``preferences-paneSync``
+  * ``preferences-paneContainers``
+
+Widget Identifiers
+------------------
+
+In order to uniquely identify a visual element a set of heuristics are used:
+
+#. If the element is one of the customizable toolbar items then that item's ID
+   is used.
+#. If the DOM element has an ID set then that is used.
+#. If the DOM element's class contains one of ``bookmark-item``,
+   ``tab-icon-sound`` or ``tab-close-button`` then that is used.
+#. If the DOM element has a ``preference`` ``key``, ``command``, ``observes`` or
+   ``data-l10n-id`` attribute then that is used.
+#. If there is still no identifier then this is repeated for the DOM element's
+   parent element.
+
+Widget Locations
+----------------
+
+The keyed scalar ``browser.ui.toolbar_widgets`` records the position of widgets in
+the UI. At startup the positions of widgets are collected and recorded by
+setting the scalar key ``<widget id>_pinned_<area>`` to true. The widget ID are
+the IDs of the elements in the DOM. The area is one of the areas listed above
+from the browser UI that can be customised.
+
+For the areas that can be controlled the scalar keys ``<area>_<off/on/newtab>`` are set.
+``newtab`` is special to the Bookmarks Toolbar and is used when the toolbar will only
+be shown on the New Tab page.
+
+Widget Customization
+--------------------
+
+The scalar ``browser.ui.customized_widgets`` records whenever the user moves a
+widget around the toolbars or shows or hides some of the areas. When a change
+occurs the scalar with the key ``<widget id>_<action>_<old area>_<new area>_<reason>``
+is incremented. The action can be one of ``move``, ``add`` or ``remove``. Old
+area and new area are the previous and now locations of the widget. In the case
+of ``add`` or ``remove`` actions one of the areas will be ``na``. For areas that
+can be shown or hidden the areas will be ``off`` or ``on``. The reason is a simple
+string that indicates what caused the move to happen (drag, context menu, etc.).
+
+UI Interactions
+---------------
+
+The scalars ``browser.ui.interaction.<area>`` record how often the use
+interacts with the browser. The area is one of those above with the addition of
+``keyboard`` for keyboard shortcuts.
+
+When an interaction occurs the widget's identifier is used as the key and the
+scalar is incremented. If the widget is provided by an add-on then the add-on
+identifier is dropped and an identifier of the form ``addonX`` is used where X
+is a number. The number used is stable for a single session. Every time the user
+moves or interacts with an add-on the same number is used but then the numbers
+for each add-on may change after Firefox has been restarted.
+
+Profile Count
+=============
+
+The scalar ``browser.engagement.profile_count`` records how many profiles have
+been used by the current Firefox installation. It reports a bucketed result,
+which will be 0 if there is an error. The raw value will be reported for 1-10,
+but above that, it will report 10 for 10-99, 100 for 100-999, 1000 for
+1000-9999, and 10000 for any values greater than that.
+
+The profile count data for an installation is stored in the root of the
+update directory in a file called ``profile_count_<install hash>.json``. The
+full path to the file will typically look something like
+``C:\ProgramData\Mozilla\profile_count_5A9E6E2F272F7AA0.json``.
+
+This value is meant to be resilient to re-installation, so that file will not
+be removed when Firefox is uninstalled.
+
+Context menu entrypoints
+========================
+
+Some context menus are re-used in multiple places. By default, we simply count
+the number of interactions per item within a context menu, and do not record
+the entrypoint that caused the context menu to open.
+
+It is possible to opt-in to recording the entrypoint that caused the context
+menu to open. This is done by adding an entry to
+``ENTRYPOINT_TRACKED_CONTEXT_MENU_IDS``, mapping the ID of the context menu
+to a keyed Scalar under ``browser.ui.interaction.``. This scalar is recorded
+only if an interaction is recorded within the context menu itself.
+
+When the keyed scalar is recorded, the key will be a unique ID for the
+trigger node that caused the context menu to open. The value is the count
+of openings from that trigger node.
diff --git a/browser/docs/CommandLineParameters.rst b/browser/docs/CommandLineParameters.rst
new file mode 100644
index 0000000000..5ba4e6df8d
--- /dev/null
+++ b/browser/docs/CommandLineParameters.rst
@@ -0,0 +1,29 @@
+=======================
+Command Line Parameters
+=======================
+
+Firefox recognizes many (many!) command line parameters.  Overview
+documentation of these parameters lives here.
+
+Known parameters
+----------------
+
+.. list-table::
+   :widths: 20 80
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``-osint``
+     - On Windows, ``-osint`` serves two purposes.  Most importantly, it signals
+       that the command line is untrusted and must be sanitized.  Command lines
+       with ``-osint`` are rejected unless they have a very specific structure,
+       usually ``firefox.exe -osint -url URL`` or ``firefox.exe -osint
+       -private-window URL``: refer to `the EnsureCommandLineSafe function
+       <https://searchfox.org/mozilla-central/rev/ead7da2d9c5400bc7034ff3f06a030531bd7e5b9/toolkit/xre/CmdLineAndEnvUtils.h#196>`_.
+       These command lines are produced by apps delegating to Firefox, and the
+       resulting URL may not be correctly quoted.  The sanitization process
+       ensures that maliciously chosen URLs do not add additional parameters to
+       Firefox.  Secondarily, the ``-osint`` parameter signals that Firefox is
+       being invoked by Windows to handle a URL: generally a registered file
+       type, e.g., ``.html``, or protocol, e.g., ``https``.
diff --git a/browser/docs/index.rst b/browser/docs/index.rst
new file mode 100644
index 0000000000..c105c59121
--- /dev/null
+++ b/browser/docs/index.rst
@@ -0,0 +1,33 @@
+=================
+Firefox Front-end
+=================
+
+This is the nascent documentation of the Firefox front-end code.
+
+.. toctree::
+   :maxdepth: 2
+
+   urlbar/index
+   BrowserUsageTelemetry
+   CommandLineParameters
+   components/enterprisepolicies/docs/index
+   extensions/formautofill/docs/index
+   components/newtab/docs/index
+   components/aboutwelcome/docs/index
+   installer/windows/installer/index
+   components/attribution/docs/index
+   /toolkit/mozapps/defaultagent/default-browser-agent/index
+   components/migration/docs/index
+   components/pagedata/docs/index
+   places/index
+   components/asrouter/docs/index
+   search/index
+   base/tabbrowser/index
+   touchbar/index
+   components/uitour/docs/index
+   branding/docs/index
+   components/storybook/docs/README.storybook.stories
+   components/storybook/docs/README.reusable-widgets.stories
+   components/storybook/docs/README.other-widgets.stories
+   components/storybook/docs/README.lit-guide.stories
+   components/storybook/docs/README.xul-and-html.stories
diff --git a/browser/docs/overview.rst b/browser/docs/overview.rst
new file mode 100644
index 0000000000..26f61ff513
--- /dev/null
+++ b/browser/docs/overview.rst
@@ -0,0 +1,105 @@
+Firefox for Desktop
+===================
+
+Desktop architecture
+--------------------
+
+One of the keys to understanding how Firefox is architected is to know that Gecko is used to render
+both web content as well as the UI of the browser. This means that, to a large extent, the UI of
+Firefox is made using web technologies like HTML, CSS, and JavaScript. For example, the document
+``chrome://browser/content/browser.xhtml`` is the markup for a single Firefox browser window. You
+can think of it almost like index.html for a webpage.
+
+The decision to use Gecko for rendering the UI was made during an era when HTML was not yet
+expressive enough or sufficient to build desktop UIs. A different markup language,
+`XUL <https://en.wikipedia.org/wiki/XUL>`_, was developed for that purpose instead, which Gecko also
+knows how to interpret. Since that time, HTML and CSS has evolved to the point where XUL is not
+strictly necessary for most use-cases. Where possible, we have been gradually migrating our UI to
+use less XUL and more standard HTML and CSS.
+
+Reusable UI Widgets
+-------------------
+
+Many of the UI widgets in use in the user interface are built as web components that can be reused.
+
+:ref:`Read more <Reusable UI widgets>`
+
+Tabbrowser
+----------
+
+The tabbrowser component manages the tabs in a browser window.
+
+:ref:`Read more <tabbrowser>`
+
+Address Bar
+-----------
+
+The address bar (varyingly also referred to as the Awesome Bar, or Quantum Bar) handles users
+entering web addresses including a popup with suggestions from various sources including history,
+bookmarks and search engines.
+
+:ref:`Read more <Address Bar>`
+
+Search
+------
+
+The search service manages the list of search engines available in the address bar.
+
+:ref:`Read more <Search>`
+
+Places
+------
+
+The places component includes the database that stores history and bookmarks as well as a set of UI
+components that present those to the user.
+
+:ref:`Read more <Places>`
+
+Firefox Sync and Application Services
+-------------------------------------
+
+Application services includes the sync engines and Firefox Accounts integration.
+
+:ref:`Read more <Services>`
+
+Developer Tools
+---------------
+
+The developer tools support web developers when building webpages but as the Firefox UI is itself
+built using web technologies it is also possible to use the developer tools to debug the Firefox UI.
+
+:ref:`Read more <Firefox DevTools Contributor Docs>`
+
+Browser Toolbox
+###############
+
+The Browser Toolbox is a way to launch the developer tools in a separate process so that they can be
+used to debug the main browser UI.
+
+:ref:`Read more <Browser Toolbox>`
+
+Profiler
+########
+
+The Firefox Profiler is the way to measure the performance of your code. Go to
+`profiler.firefox.com <https://profiler.firefox.com>`__ to enable the button in Firefox and record a
+performance profile. These profiles can be uploaded and shared. It can identify slow parts of the
+code, and reveal the underlying behavior of how code runs.
+
+Installer
+---------
+
+The Windows installer for Firefox is built with NSIS. There are currently no installers for other
+operating systems.
+
+:ref:`Read more <Installer>`
+
+Application Update
+------------------
+
+Application Update is responsible for requesting available updates from the update servers,
+downloading them, verifying their integrity and then ultimately installing them. A binary patch tool
+(bsdiff) is used to reduce the size of update files and update files are delivered in the
+bespoke mar (Mozilla ARchive) format.
+
+:ref:`Read more <Application Update>`