enabling-rules.rst (3441B)
1 Enabling Rules and Adding Plugins to Stylelint 2 ============================================== 3 4 This guide is intended to give helpful pointers on how to enable rules and add 5 plugins to our Stylelint 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 `Desktop Theme module owner and peers </mots/index.html#desktop-theme>`_. 15 16 Enabling a New Rule 17 =================== 18 19 The general process for enabling new rules is to file a bug under the 20 ``Developer Infrastructure`` product in the ``Lint and Formatting`` component. 21 22 The rule should then be added to the relevant configurations and existing issues 23 fixed. For large amounts of existing issues, we may do a staged roll-out 24 as discussed below. 25 26 Options for Roll-Outs 27 --------------------- 28 29 For rolling out new rules, we prefer that there is a plan and owner for ensuring 30 the existing failures are resolved over time. They do not always need to be fixed 31 immediately, but there should be some agreement as to how existing failures 32 are addressed, so that we do not end up with a large, potentially complicated 33 set of exclusions, or significant amounts of warnings that never get addressed. 34 35 This is not to say the developer adding the rule needs to be the owner of the 36 plan, but they should ensure that there is an agreed way forward. 37 38 There are several options available for roll-outs, depending on how many 39 errors are found and how much work it is to fix existing issues. 40 41 * Fix any issues and enable the rule everywhere 42 43 * This is most suited to cases where there are a small amount of errors which 44 are easy to fix up-front 45 46 * Enable the rule everywhere, selectively disabling the rule on existing failures 47 48 * This may be appropriate for cases where fixing the failures may take 49 a bit longer. 50 51 * Enable the rule as a warning 52 53 * This will raise issues as warnings, which will not prevent patches from 54 landing with issues, but should at least highlight them during code review. 55 * This may be more appropriate in situations where there are a large amount 56 of issues that are non-critical, such as preferring use of one method over 57 another. 58 59 * Enable the rule as an error on passing code, but a warning on code with failures 60 61 * This is a hybrid approach which is suited to cases where there is an issue 62 that is more critical, and we want to stop new cases making it into the tree, 63 and highlight the existing cases if the code gets touched. 64 65 The options here are not firmly set, the list should be used as a guide. 66 67 Where to Add 68 ------------ 69 70 Custom rules should be added in 71 :searchfox:`stylelint-plugin-mozilla/rules <tools/lint/stylelint/stylelint-plugin-mozilla/rules>` 72 and exported through the :searchfox:`index.mjs <tools/lint/stylelint/stylelint-plugin-mozilla/rules/index.mjs>` 73 file. When naming a custom rule, be sure to use the 74 :searchfox:`namespace helper function <tools/lint/stylelint/stylelint-plugin-mozilla/helpers.mjs>` 75 to prefix the rule name properly. 76 77 Where existing failures are disabled/turned to warnings, these should be handled 78 in the :searchfox:`top-level stylelint-rollouts.config.js <stylelint-rollouts.config.js>`, 79 and follow-up bugs must be filed before landing and referenced in the appropriate 80 sections. The follow-up bugs should block 81 `bug 1762027 <https://bugzilla.mozilla.org/show_bug.cgi?id=1762027>`_