Adding upstream version 110.0.1.upstream/110.0.1upstream

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

1 files changed, 187 insertions, 0 deletions

diff --git a/toolkit/components/messaging-system/schemas/index.rst b/toolkit/components/messaging-system/schemas/index.rst
new file mode 100644
index 0000000000..c110d9fc73
--- /dev/null
+++ b/toolkit/components/messaging-system/schemas/index.rst
@@ -0,0 +1,187 @@
+Messaging System Schemas
+========================
+
+Docs
+----
+
+More information about `Messaging System`__.
+
+.. __: /browser/components/newtab/content-src/asrouter/docs
+
+Messages
+--------
+
+There are JSON schemas for each type of message that the Firefox Messaging
+System handles:
+
+* `CFR URLBar Chiclet <cfr_urlbar_chiclet_schema_>`_
+* `Extension Doorhanger <extension_doorhanger_schema_>`_
+* `Infobar <infobar_schema_>`_
+* `Spotlight <spotlight_schema_>`_
+* `Toast Notification <toast_notification_schema_>`_
+* `Toolbar Badge <toolbar_badge_schema_>`_
+* `Update Action <update_action_schema_>`_
+* `Whats New <whats_new_schema_>`_
+* `Private Browsing Newtab Promo Message <pbnewtab_promo_schema_>`_
+* `Protections Panel <protections_panel_schema_>`_
+
+Together, they are combined into the `Messaging Experiments
+<messaging_experiments_schema_>`_ via a `script <make_schemas_script_>`_. This
+is the schema used for Nimbus experiments that target messaging features. All
+incoming messaging experiments will be validated against this schema.
+
+Schema Changes
+--------------
+
+To add a new message type to the Messaging Experiments schema:
+
+1. Add your message template schema.
+
+   Your message template schema only needs to define the following fields at a
+   minimum:
+
+   * ``template``: a string field that defines an identifier for your message.
+     This must be either a ``const`` or ``enum`` field.
+
+     For example, the ``template`` field of Spotlight looks like:
+
+     .. code-block:: json
+
+        { "type": "string", "const": "spotlight" }
+
+   * ``content``: an object field that defines your per-message unique content.
+
+   If your message requires ``targeting``, you must add a targeting field.
+
+   If your message supports triggering, there is a definition you can reference
+   the ``MessageTrigger`` `shared definition <Shared Definitions_>`_.
+
+   The ``groups``, ``frequency``, and ``priority`` fields will automatically be
+   inherited by your message.
+
+2. Ensure the schema has an ``$id`` member. This allows for references (e.g.,
+   ``{ "$ref": "#!/$defs/Foo" }``) to work in the bundled schema. See docs on
+   `bundling JSON schemas <jsonschema_bundling_>`_ for more information.
+
+3. Add the new schema to the list in `make-schemas.py <make_schemas_script_>`_.
+4. Build the new schema by running:
+
+   .. code-block:: shell
+
+      cd browser/components/newtab/content-src/asrouter/schemas/
+      ../../../../../../mach python make-schemas.py
+
+5. Commit the results.
+
+Likewise, if you are modifying a message schema you must rebuild the generated
+schema:
+
+.. code-block:: shell
+
+   cd browser/components/newtab/content-src/asrouter/schemas/
+   ../../../../../../mach python make-schemas.py
+
+If you do not, the `Firefox MS Schemas CI job <make_schemas_check_>`_ will fail.
+
+.. _run_make_schemas:
+
+You can run this locally via:
+
+.. code-block:: shell
+
+   cd browser/components/newtab/content-src/asrouter/schemas/
+   ../../../../../../mach xpcshell extract-test-corpus.js
+   ../../../../../../mach python make-schemas.py --check
+
+This test will re-generate the schema and compare it to
+``MessagingExperiment.schema.json``. If there is a difference, it will fail.
+The test will also validate the list of in-tree messages with the same schema
+validator that Experimenter uses to ensure that our schemas are compatible with
+Experimenter.
+
+Shared Definitions
+------------------
+
+Some definitions are shared across multiple schemas. Instead of copying and
+pasting the definitions between them and then having to manually keep them up to
+date, we keep them in a common schema that contains these defintitions:
+`FxMsCommon.schema.json <common_schema_>`_.  Any definition that will be re-used
+across multiple schemas should be added to the common schema, which will have
+its definitions bundled into the generated schema. All references to the common
+schema will be rewritten in the generated schema.
+
+The definitions listed in this file are:
+
+* ``Message``, which defines the common fields present in each FxMS message;
+* ``MessageTrigger``, which defines a method that may trigger the message to be
+  presented to the user;
+* ``localizableText``, for when either a string or a string ID (for translation
+  purposes) can be used; and
+* ``localizedText``, for when a string ID is required.
+
+An example of using the ``localizableText`` definition in a message schema follows:
+
+.. code-block:: json
+
+   {
+     "type": "object",
+     "properties": {
+       "message": {
+         "$ref": "file:///FxMSCommon.schema.json#/$defs/localizableText"
+         "description": "The message as a string or string ID"
+       },
+     }
+   }
+
+
+Schema Tests
+------------
+
+We have in-tree tests (`Test_CFRMessageProvider`_,
+`Test_OnboardingMessageProvider`_, and `Test_PanelTestProvider`_), which
+validate existing messages with the generated schema.
+
+We also have compatibility tests for ensuring that our schemas work in
+`Experimenter`_.  `Experimenter`_ uses a different JSON schema validation
+library, which is reused in the `Firefox MS Schemas CI job
+<make_schemas_check_>`_. This test validates a test corpus from
+`CFRMessageProvider`_, `OnboardingMessageProvider`_, and `PanelTestProvider`_
+with the same JSON schema validation library and configuration as Experimenter.
+
+See how to run these tests :ref:`above <run_make_schemas_>`.
+
+
+Triggers and actions
+---------------------
+
+.. toctree::
+  :maxdepth: 2
+
+  SpecialMessageActionSchemas/index
+  TriggerActionSchemas/index
+
+..  _cfr_urlbar_chiclet_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/CFR/templates/CFRUrlbarChiclet.schema.json
+..  _extension_doorhanger_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/CFR/templates/ExtensionDoorhanger.schema.json
+..  _infobar_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/CFR/templates/InfoBar.schema.json
+..  _spotlight_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/OnboardingMessage/Spotlight.schema.json
+..  _toast_notification_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/ToastNotification/ToastNotification.schema.json
+..  _toolbar_badge_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/OnboardingMessage/ToolbarBadgeMessage.schema.json
+..  _update_action_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/OnboardingMessage/UpdateAction.schema.json
+..  _whats_new_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/OnboardingMessage/WhatsNewMessage.schema.json
+..  _protections_panel_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/OnboardingMessage/ProtectionsPanelMessage.schema.json
+..  _pbnewtab_promo_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/templates/PBNewtab/NewtabPromoMessage.schema.json
+..  _messaging_experiments_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/schemas/MessagingExperiment.schema.json
+..  _common_schema: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/schemas/FxMSCommon.schema.json
+
+..  _make_schemas_script: https://searchfox.org/mozilla-central/source/browser/components/newtab/content-src/asrouter/schemas/make-schemas.py
+..  _jsonschema_bundling: https://json-schema.org/understanding-json-schema/structuring.html#bundling
+..  _make_schemas_check: https://searchfox.org/mozilla-central/source/taskcluster/ci/source-test/python.yml#425-438
+
+..  _Experimenter: https://experimenter.info
+
+..  _CFRMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/lib/CFRMessageProvider.jsm
+..  _PanelTestProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/lib/PanelTestProvider.jsm
+..  _OnboardingMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/lib/OnboardingMessageProvider.jsm
+..  _Test_CFRMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/test/xpcshell/test_CFMessageProvider.js
+..  _Test_OnboardingMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/test/xpcshell/test_OnboardingMessageProvider.js
+..  _Test_PanelTestProvider: https://searchfox.org/mozilla-central/source/browser/components/newtab/test/xpcshell/test_PanelTestProvider.js