summaryrefslogtreecommitdiffstats
path: root/docs/code-quality/lint/linters/eslint
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /docs/code-quality/lint/linters/eslint
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/code-quality/lint/linters/eslint')
-rw-r--r--docs/code-quality/lint/linters/eslint/enabling-rules.rst177
1 files changed, 177 insertions, 0 deletions
diff --git a/docs/code-quality/lint/linters/eslint/enabling-rules.rst b/docs/code-quality/lint/linters/eslint/enabling-rules.rst
new file mode 100644
index 0000000000..d20a877d4e
--- /dev/null
+++ b/docs/code-quality/lint/linters/eslint/enabling-rules.rst
@@ -0,0 +1,177 @@
+Enabling Rules and Adding Plugins to ESLint
+===========================================
+
+This guide is intended to give helpful pointers on how to enable rules and add
+plugins to our ESLint configuration.
+
+.. contents::
+ :local:
+
+General Notes
+=============
+
+* Enabling of new rules and adding plugins should happen in agreement with the
+ `JavaScript Usage, Tools and Style module owner and peers </mots/index.html#javascript-usage-tools-and-style>`_.
+
+* Enabling of rules for sub-components should also be discussed with the owner
+ and peers.
+
+ * Generally we wish to harmonize rules across the entire code base, and so
+ would prefer to avoid specialisms for different sub-components.
+ * Exceptions may be made on a sub-component basis.
+
+Enabling a New Rule
+===================
+
+The general process for enabling new rules is to file a bug under the
+``Developer Infrastructure`` product in the ``Lint and Formatting`` component.
+
+The rule should then be added to the relevant configurations and existing issues
+fixed. For large amounts of existing issues, we may do a staged roll-out
+as discussed below.
+
+Options for Roll-Outs
+---------------------
+
+For rolling out new rules, we prefer that there is a plan and owner for ensuring
+the existing failures are resolved over time. They do not always need to be fixed
+immediately, but there should be some agreement as to how existing failures
+are addressed, so that we do not end up with a large, potentially complicated
+set of exclusions, or significant amounts of warnings that never get addressed.
+
+This is not to say the developer adding the rule needs to be the owner of the
+plan, but they should ensure that there is an agreed way forward.
+
+There are several options available for roll-outs, depending on how many
+errors are found and how much work it is to fix existing issues.
+
+* Fix any issues and enable the rule everywhere
+
+ * This is most suited to cases where there are a small amount of errors which
+ are easy to fix up-front
+
+* Enable the rule everywhere, selectively disabling the rule on existing failures
+
+ * This may be appropriate for cases where fixing the failures may take
+ a bit longer.
+
+* Enable the rule as a warning
+
+ * This will raise issues as warnings, which will not prevent patches from
+ landing with issues, but should at least highlight them during code review.
+ * This may be more appropriate in situations where there are a large amount
+ of issues that are non-critical, such as preferring use of one method over
+ another.
+
+* Enable the rule as an error on passing code, but a warning on code with failures
+
+ * This is a hybrid approach which is suited to cases where there is an issue
+ that is more critical, and we want to stop new cases making it into the tree,
+ and highlight the existing cases if the code gets touched.
+
+The options here are not firmly set, the list should be used as a guide.
+
+Where to Add
+------------
+
+New rules should be added in one of the configurations in
+:searchfox:`eslint-plugin-mozilla <tools/lint/eslint/eslint-plugin-mozilla/lib/configs>`.
+
+These will then automatically be applied to the relevant places.
+eslint-plugin-mozilla is used by a few projects outside of mozilla-central,
+so they will pick up the rule addition when eslint-plugin-mozilla is next released.
+
+Where existing failures are disabled/turned to warnings, these should be handled
+in the :searchfox:`top-level .eslintrc.js file <.eslintrc.js>`, and follow-up bugs
+must be filed before landing and referenced in the appropriate sections. The
+follow-up bugs should block
+`bug 1596191 <https://bugzilla.mozilla.org/show_bug.cgi?id=1596191>`_
+
+Adding a New ESLint Plugin
+==========================
+
+License checks
+--------------
+
+When a new plugin is proposed, it should be checked to ensure that the licenses
+of the node module and all dependent node modules are compatible with the Mozilla
+code base. Mozilla employees can consult the
+`Licensing & Contributor Agreements Runbook <https://mozilla-hub.atlassian.net/l/cp/bgfp6Be7>`_
+for more details.
+
+A site such as `npmgraph <https://npmgraph.js.org/>`_ can help with checking
+licenses.
+
+When filing the bug or reviewing a patch, it should be stated if the module
+has passed the license checks.
+
+Adding to the Repository
+------------------------
+
+If the new plugin is going to have rules defined within a configuration within
+eslint-plugin-mozilla, then the module should be referenced in the peer
+dependencies of
+:searchfox:`eslint-plugin-mozilla's package.json<tools/lint/eslint/eslint-plugin-mozilla/package.json>`
+file.
+
+To add the new module to the node system, run:
+
+.. code-block:: shell
+
+ ./mach npm install --save-exact --save-dev packagename
+
+We use exact version matching to make it explicit about the version we are using
+and when we upgrade the versions.
+
+The plugin can then be used with ESLint in the
+`normal way <https://eslint.org/docs/latest/use/configure/plugins>`_.
+
+Packaging node_modules
+----------------------
+
+For our continuous integration (CI) builders, we package ``node_modules`` for
+both the top-level directory, and eslint-plugin-mozilla. These are uploaded to
+our CI before the patch is released.
+
+Currently `Mark Banner (standard8) <https://people.mozilla.org/s?query=standard8>`_
+is the only person that does this regularly, and will be automatically added as
+a blocking reviewer on patches that touch the relevant ``package.json`` files.
+
+A Release Engineering team member would likely have permissions to upload the
+files as well.
+
+To upload the files, the process is:
+
+* Obtain ToolTool credentials for the public tooltool upload space.
+
+ * Download the `taskcluster shell from here <https://github.com/taskcluster/taskcluster/tree/main/clients/client-shell>`_,
+ if you haven't already.
+ * Run the following command. This will open a page for you to log in, and
+ set environment variables for the following commands to use.
+
+.. code-block:: shell
+
+ eval `TASKCLUSTER_ROOT_URL=https://firefox-ci-tc.services.mozilla.com taskcluster signin -s 'project:releng:services/tooltool/api/upload/public'`
+
+* Upload the eslint-plugin-mozilla packages:
+
+.. code-block:: shell
+
+ cd tools/lint/eslint/eslint-plugin-mozilla/
+ ./update.sh
+ <follow the instructions>
+
+* Upload the top-level packages:
+
+.. code-block:: shell
+
+ cd ..
+ ./update.sh
+ <follow the instructions>
+
+* Add the changes to the commit that changes ``package.json``.
+
+The update scripts automatically clean out the ``node_modules`` directories,
+removes the ``package-lock.json`` files, and then does a fresh installation. This
+helps to ensure a "clean" directory with only the required modules, and an up to
+date ``package-lock.json`` file.