enabling-rules.rst (5006B)
1 Enabling Rules and Adding Plugins to ESLint 2 =========================================== 3 4 This guide is intended to give helpful pointers on how to enable rules and add 5 plugins to our ESLint configuration. 6 7 .. contents:: 8 :local: 9 10 General Notes 11 ============= 12 13 * Enabling of new rules and adding plugins should happen in agreement with the 14 `JavaScript Usage, Tools and Style module owner and peers </mots/index.html#javascript-usage-tools-and-style>`_. 15 16 * Enabling of rules for sub-components should also be discussed with the owner 17 and peers. 18 19 * Generally we wish to harmonize rules across the entire code base, and so 20 would prefer to avoid specialisms for different sub-components. 21 * Exceptions may be made on a sub-component basis. 22 23 Enabling a New Rule 24 =================== 25 26 The general process for enabling new rules is to file a bug under the 27 ``Developer Infrastructure`` product in the ``Lint and Formatting`` component. 28 29 The rule should then be added to the relevant configurations and existing issues 30 fixed. For large amounts of existing issues, we may do a staged roll-out 31 as discussed below. 32 33 Options for Roll-Outs 34 --------------------- 35 36 For rolling out new rules, we prefer that there is a plan and owner for ensuring 37 the existing failures are resolved over time. They do not always need to be fixed 38 immediately, but there should be some agreement as to how existing failures 39 are addressed, so that we do not end up with a large, potentially complicated 40 set of exclusions, or significant amounts of warnings that never get addressed. 41 42 This is not to say the developer adding the rule needs to be the owner of the 43 plan, but they should ensure that there is an agreed way forward. 44 45 There are several options available for roll-outs, depending on how many 46 errors are found and how much work it is to fix existing issues. 47 48 * Fix any issues and enable the rule everywhere 49 50 * This is most suited to cases where there are a small amount of errors which 51 are easy to fix up-front 52 53 * Enable the rule everywhere, selectively disabling the rule on existing failures 54 55 * This may be appropriate for cases where fixing the failures may take 56 a bit longer. 57 58 * Enable the rule as a warning 59 60 * This will raise issues as warnings, which will not prevent patches from 61 landing with issues, but should at least highlight them during code review. 62 * This may be more appropriate in situations where there are a large amount 63 of issues that are non-critical, such as preferring use of one method over 64 another. 65 66 * Enable the rule as an error on passing code, but a warning on code with failures 67 68 * This is a hybrid approach which is suited to cases where there is an issue 69 that is more critical, and we want to stop new cases making it into the tree, 70 and highlight the existing cases if the code gets touched. 71 72 The options here are not firmly set, the list should be used as a guide. 73 74 Where to Add 75 ------------ 76 77 New rules should be added in one of the configurations in 78 :searchfox:`eslint-plugin-mozilla <tools/lint/eslint/eslint-plugin-mozilla/lib/configs>`. 79 80 These will then automatically be applied to the relevant places. 81 eslint-plugin-mozilla is used by a few projects outside of mozilla-central, 82 so they will pick up the rule addition when eslint-plugin-mozilla is next released. 83 84 Where existing failures are disabled/turned to warnings, these should be handled 85 in the :searchfox:`top-level .eslintrc-rollouts.js file <..eslintrc-rollouts.js>`, 86 and follow-up bugs must be filed before landing and referenced in the appropriate 87 sections. The follow-up bugs should block 88 `bug 1596191 <https://bugzilla.mozilla.org/show_bug.cgi?id=1596191>`_ 89 90 Adding a New ESLint Plugin 91 ========================== 92 93 License checks 94 -------------- 95 96 When a new plugin is proposed, it should be checked to ensure that the licenses 97 of the node module and all dependent node modules are compatible with the Mozilla 98 code base. Mozilla employees can consult the 99 `Licensing & Contributor Agreements Runbook <https://mozilla-hub.atlassian.net/l/cp/bgfp6Be7>`_ 100 for more details. 101 102 A site such as `npmgraph <https://npmgraph.js.org/>`_ can help with checking 103 licenses. 104 105 When filing the bug or reviewing a patch, it should be stated if the module 106 has passed the license checks. 107 108 Adding to the Repository 109 ------------------------ 110 111 If the new plugin is going to have rules defined within a configuration within 112 eslint-plugin-mozilla, then the module should be referenced in the peer 113 dependencies of 114 :searchfox:`eslint-plugin-mozilla's package.json<tools/lint/eslint/eslint-plugin-mozilla/package.json>` 115 file. 116 117 To add the new module to the node system, run: 118 119 .. code-block:: shell 120 121 ./mach npm install --save-exact --save-dev packagename 122 123 We use exact version matching to make it explicit about the version we are using 124 and when we upgrade the versions. 125 126 The plugin can then be used with ESLint in the 127 `normal way <https://eslint.org/docs/latest/use/configure/plugins>`_.