diff options
Diffstat (limited to 'docs/code-quality')
| -rw-r--r-- | docs/code-quality/lint/create.rst | 2 | ||||
| -rw-r--r-- | docs/code-quality/lint/linters/condprof-addons.rst | 10 | ||||
| -rw-r--r-- | docs/code-quality/lint/linters/perfdocs.rst | 71 | ||||
| -rw-r--r-- | docs/code-quality/static-analysis/existing.rst | 2 |
4 files changed, 65 insertions, 20 deletions
diff --git a/docs/code-quality/lint/create.rst b/docs/code-quality/lint/create.rst index 4da59b83a0..f3afe59ab5 100644 --- a/docs/code-quality/lint/create.rst +++ b/docs/code-quality/lint/create.rst @@ -347,7 +347,7 @@ Adding the linter to the CI First, the job will have to be declared in Taskcluster. -This should be done in the `mozlint Taskcluster configuration <https://searchfox.org/mozilla-central/source/taskcluster/ci/source-test/mozlint.yml>`_. +This should be done in the `mozlint Taskcluster configuration <https://searchfox.org/mozilla-central/source/taskcluster/kinds/source-test/mozlint.yml>`_. You will need to define a symbol, how it is executed and on what kind of change. For example, for ruff, the configuration is the following: diff --git a/docs/code-quality/lint/linters/condprof-addons.rst b/docs/code-quality/lint/linters/condprof-addons.rst index c302eef5be..ca9c869d09 100644 --- a/docs/code-quality/lint/linters/condprof-addons.rst +++ b/docs/code-quality/lint/linters/condprof-addons.rst @@ -5,7 +5,7 @@ CondProf Addons is a linter for condprof customization JSON files (see :searchfo it reports linting errors if: - any of the addons required by the customization files (e.g. see :searchfox:`testing/condprofile/condprof/customization/webext.json`) - is not found in the tar file fetched through the `firefox-addons` fetch task (see :searchfox:`taskcluster/ci/fetch/browsertime.yml`) + is not found in the tar file fetched through the `firefox-addons` fetch task (see :searchfox:`taskcluster/kinds/fetch/browsertime.yml`) - or the expected `firefox-addons` fetch task has not been found Run Locally @@ -37,7 +37,7 @@ XPI file is missing from the firefox-addons.tar archive This linting errors is expected to be reported if the linter detected that a confprof customization file requires an addon but the related xpi filename is not included in the firefox-addons.tar file fetched -through the `firefox-addons` fetch task (see :searchfox:`taskcluster/ci/fetch/browsertime.yml`). +through the `firefox-addons` fetch task (see :searchfox:`taskcluster/kinds/fetch/browsertime.yml`). If the patch or phabricator revision is not meant to be landed, but only used as a temporary patch pushed on try or only applied locally (e.g. to run the tp6/tp6m webextensions perftests with a given @@ -50,14 +50,14 @@ the linting error have to be fixed before or along landing the change, either by - removing the addition to the customization file if it wasn't intended to include that addon to all runs of the tp6/tp6m webextensions perftests -- updating the `firefox-addons` fetch task as defined in :searchfox:`taskcluster/ci/fetch/browsertime.yml` +- updating the `firefox-addons` fetch task as defined in :searchfox:`taskcluster/kinds/fetch/browsertime.yml` by creating a pull request in the github repository where the asset is stored, and ask a review from a peer of the `#webextensions-reviewer` and `#perftests-reviewers` review groups. firefox-addons taskcluster config 'add-prefix' attribute should be set to 'firefox-addons/' ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If this linting error is hit, then the `firefox-addons` task defined in :searchfox:`taskcluster/ci/fetch/browsertime.yml` +If this linting error is hit, then the `firefox-addons` task defined in :searchfox:`taskcluster/kinds/fetch/browsertime.yml` is missing the `add-prefix` attribute or its value is not set to the expected 'firefox-addons/' subdir name. This is enforced as a linting rule because when the condprof utility is going to build a conditioned profile @@ -69,7 +69,7 @@ names are already available in `$MOZ_FETCHES_DIR/firefox-addons`. firefox-addons taskcluser fetch config section not found ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This linting error is hit if the linter does not find the expected `firefox-addons` task defined in :searchfox:`taskcluster/ci/fetch/browsertime.yml` +This linting error is hit if the linter does not find the expected `firefox-addons` task defined in :searchfox:`taskcluster/kinds/fetch/browsertime.yml` or it is missing the expected `fetch` attribute. Configuration diff --git a/docs/code-quality/lint/linters/perfdocs.rst b/docs/code-quality/lint/linters/perfdocs.rst index 1ec2e33e68..9a5c6f1d2d 100644 --- a/docs/code-quality/lint/linters/perfdocs.rst +++ b/docs/code-quality/lint/linters/perfdocs.rst @@ -14,21 +14,42 @@ The mozlint integration of PerfDocs can be run using mach: $ mach lint --linter perfdocs . +Documentation can be regenerated for performance tests by including the ``--fix`` flag: + +.. parsed-literal:: + + $ mach lint --linter perfdocs . --fix + Configuration ------------- -There are no configuration options available for this linter. It scans the full source tree under ``testing``, looking for folders named ``perfdocs`` and then validates their content. This has only been implemented for Raptor so far, but Talos will be added in the future. We also hope to expand this to search outside the ``testing`` directory. +There are no configuration options available for this linter. It scans the full source tree under ``testing``, looking for folders named ``perfdocs``, validates their content, and regenerates the documentation (if ``--fix`` is provided). This has been implemented for all performance testing harnesses, and the documentation generated gets displayed in :ref:`Performance Testing`. -The ``perfdocs`` folders, there needs to be an ``index.rst`` file and it needs to contain the string ``{documentation}`` in some location in the file which is where the test documentation will be placed. The folders must also have a ``config.yml`` file following this schema: +In the ``perfdocs`` folders, there needs to be an ``index.rst`` file and it needs to contain the string ``{documentation}`` in some location in the file which is where the test documentation will be placed. The folders must also have a ``config.yml`` file following this schema: .. code-block:: python CONFIG_SCHEMA = { + "definitions": { + "metrics_schema": { + "metric_name": { + "type": "object", + "properties": { + "aliases": {"type": "array", "items": {"type": "string"}}, + "description": {"type": "string"}, + "matcher": {"type": "string"}, + }, + "required": ["description", "aliases"], + }, + }, + }, "type": "object", "properties": { "name": {"type": "string"}, "manifest": {"type": "string"}, + "static-only": {"type": "boolean"}, + "metrics": {"$ref": "#/definitions/metrics_schema"}, "suites": { "type": "object", "properties": { @@ -39,22 +60,17 @@ The ``perfdocs`` folders, there needs to be an ``index.rst`` file and it needs t "type": "object", "properties": { "test_name": {"type": "string"}, - } + }, }, "description": {"type": "string"}, + "owner": {"type": "string"}, }, - "required": [ - "description" - ] + "required": ["description"], } - } - } + }, + }, }, - "required": [ - "name", - "manifest", - "suites" - ] + "required": ["name", "manifest", "static-only", "suites"], } Here is an example of a configuration file for the Raptor framework: @@ -75,6 +91,35 @@ Here is an example of a configuration file for the Raptor framework: tests: wasm: "All wasm tests." +Metrics that produce alerts can also be documented like so: + +.. parsed-literal:: + + name: raptor + manifest: testing/raptor/raptor/raptor.toml + metrics: + "First Paint": + description: "The description of the metric." + aliases: + - fcp + - anAliasForFCP + # Optional regex to match the metrics found in the tests with this + # documented metric + matcher: f.* + suites: + desktop: + description: "Desktop tests." + tests: + raptor-tp6: "Raptor TP6 tests." + mobile: + description: "Mobile tests" + benchmarks: + description: "Benchmark tests." + tests: + wasm: "All wasm tests." + +The documented metrics must exist in the tests for the suite. If they are not, then validation will fail. The same is true if a metric in a test is not documented. Also, if ``metrics`` are defined, then a ``metrics.rst`` file is expected to be found in the ``perfdocs`` folder for the given suite. It must contain the string ``{metrics_documentation}`` where the documentation should be added. The ``metrics.rst`` is renamed ``{suite-name}-metrics.rst`` in the generated folder, so if it needs to be linked to in the ``index.rst`` file, it should contain a ``{metrics_rst_name}`` string for where the link should be added - it's expected to be found in a toctree section. + Note that there needs to be a FrameworkGatherer implemented for the framework being documented since each of them may have different ways of parsing test manifests for the tests. See `RaptorGatherer <https://searchfox.org/mozilla-central/source/tools/lint/perfdocs/framework_gatherers.py>`_ for an example gatherer that was implemented for Raptor. Sources diff --git a/docs/code-quality/static-analysis/existing.rst b/docs/code-quality/static-analysis/existing.rst index 9b20650ad0..dd38051dc7 100644 --- a/docs/code-quality/static-analysis/existing.rst +++ b/docs/code-quality/static-analysis/existing.rst @@ -96,7 +96,7 @@ Regression Testing In order to prevent regressions in our clang-tidy based static analysis, we have created a -:searchfox:`task <taskcluster/ci/static-analysis-autotest/kind.yml>` +:searchfox:`task <taskcluster/kinds/static-analysis-autotest/kind.yml>` on automation. This task runs on each commit and launches a test suite that is integrated into mach. |