Merge pull request #205 from vuejs/style-guide-alignment

Style Guide Alignment

Author: michalsnik

.eslintignore

@@ -1,4 +1,4 @@
 node_modules
-lib/recommended-rules.js
+lib/*-rules.js
 coverage
 .nyc_output

.gitignore

@@ -3,3 +3,4 @@
 /tests/integrations/*/node_modules
 /node_modules
 /test.*
+yarn.lock

README.md

@@ -75,87 +75,109 @@ Vue.component('AsyncComponent', (resolve, reject) => {
 ## :gear: Configs
 
 This plugin provides two predefined configs:
-- `plugin:vue/base` - contains necessary settings for this plugin to work properly
-- `plugin:vue/recommended` - extends base config with recommended rules (the ones with check mark :white_check_mark: in the table below)
+- `plugin:vue/base` - Settings and rules to enable correct ESLint parsing
+- `plugin:vue/essential` - Above, plus rules to prevent errors or unintended behavior
+- `plugin:vue/strongly-recommended` - Above, plus rules to considerably improve code readability and/or dev experience
+- `plugin:vue/recommended` - Above, plus rules to enforce subjective community defaults to ensure consistency
 
 ## :bulb: Rules
 
-Rules are grouped by category to help you understand their purpose.
+Rules are grouped by priority to help you understand their purpose. The `--fix` option on the command line automatically fixes problems reported by rules which have a wrench :wrench: below.
 
-No rules are enabled by `plugin:vue/base` config. The `plugin:vue/recommended` config enables rules that report common problems, which have a check mark :white_check_mark: below.
+<!--RULES_TABLE_START-->
 
-The `--fix` option on the command line automatically fixes problems reported by rules which have a wrench :wrench: below.
+### Base Rules (Enabling Correct ESLint Parsing)
 
-<!--RULES_TABLE_START-->
+Enforce all the rules in this category, as well as all higher priority rules, with:
 
-### Possible Errors
+``` json
+"extends": "plugin:vue/base"
+```
 
 |    | Rule ID | Description |
 |:---|:--------|:------------|
+|  | [jsx-uses-vars](./docs/rules/jsx-uses-vars.md) | prevent variables used in JSX to be marked as unused |
+
+
+### Priority A: Essential (Error Prevention)
+
+Enforce all the rules in this category, as well as all higher priority rules, with:
+
+``` json
+"extends": "plugin:vue/essential"
+```
+
+|    | Rule ID | Description |
+|:---|:--------|:------------|
+|  | [no-async-in-computed-properties](./docs/rules/no-async-in-computed-properties.md) | disallow asynchronous actions in computed properties |
 |  | [no-dupe-keys](./docs/rules/no-dupe-keys.md) | disallow duplication of field names |
-| :white_check_mark: | [no-parsing-error](./docs/rules/no-parsing-error.md) | disallow parsing errors in `<template>` |
+|  | [no-duplicate-attributes](./docs/rules/no-duplicate-attributes.md) | disallow duplication of attributes |
+|  | [no-parsing-error](./docs/rules/no-parsing-error.md) | disallow parsing errors in `<template>` |
 |  | [no-reserved-keys](./docs/rules/no-reserved-keys.md) | disallow overwriting reserved keys |
 |  | [no-shared-component-data](./docs/rules/no-shared-component-data.md) | enforce component's data property to be a function |
+|  | [no-side-effects-in-computed-properties](./docs/rules/no-side-effects-in-computed-properties.md) | disallow side effects in computed properties |
 |  | [no-template-key](./docs/rules/no-template-key.md) | disallow `key` attribute on `<template>` |
+|  | [no-textarea-mustache](./docs/rules/no-textarea-mustache.md) | disallow mustaches in `<textarea>` |
 |  | [no-unused-vars](./docs/rules/no-unused-vars.md) | disallow unused variable definitions of v-for directives or scope attributes |
+|  | [require-component-is](./docs/rules/require-component-is.md) | require `v-bind:is` of `<component>` elements |
 |  | [require-render-return](./docs/rules/require-render-return.md) | enforce render function to always return value |
+|  | [require-v-for-key](./docs/rules/require-v-for-key.md) | require `v-bind:key` with `v-for` directives |
 |  | [require-valid-default-prop](./docs/rules/require-valid-default-prop.md) | enforce props default values to be valid |
 |  | [return-in-computed-property](./docs/rules/return-in-computed-property.md) | enforce that a return statement is present in computed property |
-| :white_check_mark: | [valid-template-root](./docs/rules/valid-template-root.md) | enforce valid template root |
-| :white_check_mark: | [valid-v-bind](./docs/rules/valid-v-bind.md) | enforce valid `v-bind` directives |
-| :white_check_mark: | [valid-v-cloak](./docs/rules/valid-v-cloak.md) | enforce valid `v-cloak` directives |
-| :white_check_mark: | [valid-v-else-if](./docs/rules/valid-v-else-if.md) | enforce valid `v-else-if` directives |
-| :white_check_mark: | [valid-v-else](./docs/rules/valid-v-else.md) | enforce valid `v-else` directives |
-| :white_check_mark: | [valid-v-for](./docs/rules/valid-v-for.md) | enforce valid `v-for` directives |
-| :white_check_mark: | [valid-v-html](./docs/rules/valid-v-html.md) | enforce valid `v-html` directives |
-| :white_check_mark: | [valid-v-if](./docs/rules/valid-v-if.md) | enforce valid `v-if` directives |
-| :white_check_mark: | [valid-v-model](./docs/rules/valid-v-model.md) | enforce valid `v-model` directives |
-| :white_check_mark: | [valid-v-on](./docs/rules/valid-v-on.md) | enforce valid `v-on` directives |
-| :white_check_mark: | [valid-v-once](./docs/rules/valid-v-once.md) | enforce valid `v-once` directives |
-| :white_check_mark: | [valid-v-pre](./docs/rules/valid-v-pre.md) | enforce valid `v-pre` directives |
-| :white_check_mark: | [valid-v-show](./docs/rules/valid-v-show.md) | enforce valid `v-show` directives |
-| :white_check_mark: | [valid-v-text](./docs/rules/valid-v-text.md) | enforce valid `v-text` directives |
-
-
-### Best Practices
-
-|    | Rule ID | Description |
-|:---|:--------|:------------|
-| :wrench: | [html-end-tags](./docs/rules/html-end-tags.md) | enforce end tag style |
-|  | [no-async-in-computed-properties](./docs/rules/no-async-in-computed-properties.md) | disallow asynchronous actions in computed properties |
-| :white_check_mark: | [no-confusing-v-for-v-if](./docs/rules/no-confusing-v-for-v-if.md) | disallow confusing `v-for` and `v-if` on the same element |
-|  | [no-duplicate-attributes](./docs/rules/no-duplicate-attributes.md) | disallow duplication of attributes |
-|  | [no-side-effects-in-computed-properties](./docs/rules/no-side-effects-in-computed-properties.md) | disallow side effects in computed properties |
-| :white_check_mark: | [no-textarea-mustache](./docs/rules/no-textarea-mustache.md) | disallow mustaches in `<textarea>` |
-|  | [order-in-components](./docs/rules/order-in-components.md) | enforce order of properties in components |
-| :white_check_mark: | [require-component-is](./docs/rules/require-component-is.md) | require `v-bind:is` of `<component>` elements |
-|  | [require-default-prop](./docs/rules/require-default-prop.md) | require default value for props |
-|  | [require-prop-types](./docs/rules/require-prop-types.md) | require type definitions in props |
-| :white_check_mark: | [require-v-for-key](./docs/rules/require-v-for-key.md) | require `v-bind:key` with `v-for` directives |
-|  | [this-in-template](./docs/rules/this-in-template.md) | enforce usage of `this` in template |
-
-
-### Stylistic Issues
+|  | [valid-template-root](./docs/rules/valid-template-root.md) | enforce valid template root |
+|  | [valid-v-bind](./docs/rules/valid-v-bind.md) | enforce valid `v-bind` directives |
+|  | [valid-v-cloak](./docs/rules/valid-v-cloak.md) | enforce valid `v-cloak` directives |
+|  | [valid-v-else-if](./docs/rules/valid-v-else-if.md) | enforce valid `v-else-if` directives |
+|  | [valid-v-else](./docs/rules/valid-v-else.md) | enforce valid `v-else` directives |
+|  | [valid-v-for](./docs/rules/valid-v-for.md) | enforce valid `v-for` directives |
+|  | [valid-v-html](./docs/rules/valid-v-html.md) | enforce valid `v-html` directives |
+|  | [valid-v-if](./docs/rules/valid-v-if.md) | enforce valid `v-if` directives |
+|  | [valid-v-model](./docs/rules/valid-v-model.md) | enforce valid `v-model` directives |
+|  | [valid-v-on](./docs/rules/valid-v-on.md) | enforce valid `v-on` directives |
+|  | [valid-v-once](./docs/rules/valid-v-once.md) | enforce valid `v-once` directives |
+|  | [valid-v-pre](./docs/rules/valid-v-pre.md) | enforce valid `v-pre` directives |
+|  | [valid-v-show](./docs/rules/valid-v-show.md) | enforce valid `v-show` directives |
+|  | [valid-v-text](./docs/rules/valid-v-text.md) | enforce valid `v-text` directives |
+
+
+### Priority B: Strongly Recommended (Improving Readability)
+
+Enforce all the rules in this category, as well as all higher priority rules, with:
+
+``` json
+"extends": "plugin:vue/strongly-recommended"
+```
 
 |    | Rule ID | Description |
 |:---|:--------|:------------|
 | :wrench: | [attribute-hyphenation](./docs/rules/attribute-hyphenation.md) | enforce attribute naming style in template |
+| :wrench: | [html-end-tags](./docs/rules/html-end-tags.md) | enforce end tag style |
 | :wrench: | [html-indent](./docs/rules/html-indent.md) | enforce consistent indentation in `<template>` |
-|  | [html-quotes](./docs/rules/html-quotes.md) | enforce quotes style of HTML attributes |
 | :wrench: | [html-self-closing](./docs/rules/html-self-closing.md) | enforce self-closing style |
 |  | [max-attributes-per-line](./docs/rules/max-attributes-per-line.md) | enforce the maximum number of attributes per line |
 | :wrench: | [mustache-interpolation-spacing](./docs/rules/mustache-interpolation-spacing.md) | enforce unified spacing in mustache interpolations |
 | :wrench: | [name-property-casing](./docs/rules/name-property-casing.md) | enforce specific casing for the name property in Vue components |
 | :wrench: | [no-multi-spaces](./docs/rules/no-multi-spaces.md) | disallow multiple spaces |
+|  | [require-default-prop](./docs/rules/require-default-prop.md) | require default value for props |
+|  | [require-prop-types](./docs/rules/require-prop-types.md) | require type definitions in props |
 | :wrench: | [v-bind-style](./docs/rules/v-bind-style.md) | enforce `v-bind` directive style |
 | :wrench: | [v-on-style](./docs/rules/v-on-style.md) | enforce `v-on` directive style |
 
 
-### Variables
+### Priority C: Recommended (Minimizing Arbitrary Choices and Cognitive Overhead)
+
+Enforce all the rules in this category, as well as all higher priority rules, with:
+
+``` json
+"extends": "plugin:vue/recommended"
+```
 
 |    | Rule ID | Description |
 |:---|:--------|:------------|
-| :white_check_mark: | [jsx-uses-vars](./docs/rules/jsx-uses-vars.md) | prevent variables used in JSX to be marked as unused |
+|  | [html-quotes](./docs/rules/html-quotes.md) | enforce quotes style of HTML attributes |
+|  | [no-confusing-v-for-v-if](./docs/rules/no-confusing-v-for-v-if.md) | disallow confusing `v-for` and `v-if` on the same element |
+|  | [order-in-components](./docs/rules/order-in-components.md) | enforce order of properties in components |
+|  | [this-in-template](./docs/rules/this-in-template.md) | enforce usage of `this` in template |
 
 ### Deprecated
 

docs/rules/attribute-hyphenation.md

@@ -15,41 +15,25 @@ Default casing is set to `always`
 :+1: Examples of **correct** code`:
 
 ```html
-<template>
-  <foo my-prop="prop">
-    <a onClick="return false"></a>
-  </foo>
-</template>
+<MyComponent my-prop="prop"/>
 ```
 
 :-1: Examples of **incorrect** code`:
 
 ```html
-<template>
-  <foo myProp="prop">
-    <a onClick="return false"></a>
-  </foo>
-</template>
+<MyComponent myProp="prop"/>
 ```
 
 ### `"never"` - Don't use hyphenated name. (It errors on hyphens except `data-` and `aria-`.)
 
 :+1: Examples of **correct** code`:
 
 ```html
-<template>
-  <foo myProp="prop">
-    <a onClick="return false"></a>
-  </foo>
-</template>
+<MyComponent myProp="prop"/>
 ```
 
 :-1: Examples of **incorrect** code`:
 
 ```html
-<template>
-  <foo my-prop="prop">
-    <a onClick="return false"></a>
-  </foo>
-</template>
+<MyComponent my-prop="prop"/>
 ```

docs/rules/html-end-tags.md

@@ -17,30 +17,21 @@ This rule reports the following elements:
 :-1: Examples of **incorrect** code for this rule:
 
 ```html
-<template>
-    <div>
-        <div>
-        <p>
-        <p>
-        <input></input>
-        <br></br>
-    </div>
-</template>
+<div>
+<p>
+<p>
+<input></input>
+<br></br>
 ```
 
 :+1: Examples of **correct** code for this rule:
 
 ```html
-<template>
-    <div>
-        <div></div>
-        <p></p>
-        <p></p>
-        <div />
-        <input>
-        <br>
-    </div>
-</template>
+<div></div>
+<p></p>
+<p></p>
+<input>
+<br>
 ```
 
 ## :wrench: Options

docs/rules/html-indent.md

@@ -65,7 +65,7 @@ This rule enforces a consistent indentation style in `<template>`. The default s
 }
 ```
 
-- `type` (`number | "tab"`) ... The type of indentation. Default is `4`. If this is a number, it's the number of spaces for one indent. If this is `"tab"`, it uses one tab for one indent.
+- `type` (`number | "tab"`) ... The type of indentation. Default is `2`. If this is a number, it's the number of spaces for one indent. If this is `"tab"`, it uses one tab for one indent.
 - `attribute` (`integer`) ... The multiplier of indentation for attributes. Default is `1`.
 - `closeBracket` (`integer`) ... The multiplier of indentation for right brackets. Default is `0`.
 - `ignores` (`string[]`) ... The selector to ignore nodes. The AST spec is [here](https://github.com/mysticatea/vue-eslint-parser/blob/master/docs/ast.md). You can use [esquery](https://github.com/estools/esquery#readme) to select nodes. Default is an empty array.

docs/rules/html-quotes.md

@@ -15,43 +15,27 @@ This rule reports the quotes of attributes if it is different to configured quot
 :-1: Examples of **incorrect** code for this rule:
 
 ```html
-<template>
-    <div>
-        <img src='./logo.png'>
-        <img src=./logo.png>
-    </div>
-</template>
+<img src='./logo.png'>
+<img src=./logo.png>
 ```
 
 :+1: Examples of **correct** code for this rule:
 
 ```html
-<template>
-    <div>
-        <img src="./logo.png">
-    </div>
-</template>
+<img src="./logo.png">
 ```
 
 :-1: Examples of **incorrect** code for this rule with `"single"` option:
 
 ```html
-<template>
-    <div>
-        <img src="./logo.png">
-        <img src=./logo.png>
-    </div>
-</template>
+<img src="./logo.png">
+<img src=./logo.png>
 ```
 
 :+1: Examples of **correct** code for this rule with `"single"` option:
 
 ```html
-<template>
-    <div>
-        <img src='./logo.png'>
-    </div>
-</template>
+<img src='./logo.png'>
 ```
 
 ## :wrench: Options

docs/rules/html-self-closing.md

@@ -4,8 +4,8 @@
 
 In Vue.js template, we can use either two styles for elements which don't have their content.
 
-1. `<your-component></your-component>`
-2. `<your-component />` (self-closing)
+1. `<YourComponent></YourComponent>`
+2. `<YourComponent/>` (self-closing)
 
 Self-closing is simple and shorter, but it's not supported in raw HTML.
 This rule helps you to unify the self-closing style.
@@ -16,20 +16,20 @@ This rule has options which specify self-closing style for each context.
 
 ```json
 {
-    "html-self-closing": [2, {
-        "html": {
-            "normal": "never",
-            "void": "never",
-            "component": "always"
-        },
-        "svg": "always",
-        "math": "always"
-    }]
+  "html-self-closing": ["error", {
+    "html": {
+      "void": "never",
+      "normal": "always",
+      "component": "always"
+    },
+    "svg": "always",
+    "math": "always"
+  }]
 }
 ```
 
-- `html.normal` (`"never"` by default) ... The style of well-known HTML elements except void elements.
 - `html.void` (`"never"` by default) ... The style of well-known HTML void elements.
+- `html.normal` (`"always"` by default) ... The style of well-known HTML elements except void elements.
 - `html.component` (`"always"` by default) ... The style of Vue.js custom components.
 - `svg`(`"always"` by default) .... The style of well-known SVG elements.
 - `math`(`"always"` by default) .... The style of well-known MathML elements.
@@ -45,25 +45,18 @@ Every option can be set to one of the following values:
 :-1: Examples of **incorrect** code for this rule:
 
 ```html
-/*eslint html-self-closing: "error"*/
-
-<template>
-    <div />
-    <img />
-    <your-component></your-component>
-    <svg><path d=""></path></svg>
-</template>
+<div></div>
+<img/>
+<img></img>
+<MyComponent/></MyComponent>
+<svg><path d=""></path></svg>
 ```
 
 :+1: Examples of **correct** code for this rule:
 
 ```html
-/*eslint html-self-closing: "error"*/
-
-<template>
-    <div></div>
-    <img>
-    <your-component />
-    <svg><path d="" /></svg>
-</template>
+<div/>
+<img>
+<MyComponent/>
+<svg><path d=""/></svg>
 ```