Docs: Describe values under Extending Configuration Files (refs #6240)

docs/user-guide/configuring.md

@@ -550,84 +550,125 @@ The complete configuration hierarchy, from highest precedence to lowest preceden
 
 ## Extending Configuration Files
 
-If you want to extend a specific configuration file, you can use the `extends` property and specify the path to the file. The path can be either relative or absolute.
+A configuration file can "extend" one or more "child" configurations to override a "base" set of rules.
 
-Configurations can be extended by using:
+The `extends` property value is either a string or an array of strings (in which each additional configuration overrides the preceding configurations) that can specify any of the following:
 
-1. YAML file
-1. JSON file
-1. JS file
-1. Shareable configuration package
+* the recommended rules
+* shareable configuration packages
+* configurations from plugins
+* configuration files
+* all core rules
 
-The extended configuration provides base rules, which can be overridden by the configuration that references it. For example:
+If a "child" configuration has an `extends` property, ESLint extends the configuration recursively.
 
-```js
-{
-    "extends": "./node_modules/coding-standard/.eslintrc",
+The `rules` property can do any of the following to override the "base" set of rules:
+
+* specify different options for rules
+* turn off rules
+* turn on additional rules
+
+
+### Extending the recommended rules
+
+An `extends` property value `"eslint:recommended"` enables a subset of core rules that report common problems, which have a check mark (recommended) on the [rules page](http://eslint.org/docs/rules/). The recommended subset can change only at major versions of ESLint.
 
+The `eslint --init` command can create a configuration so you can extend the recommended rules.
+
+```js
+module.exports = {
+    "extends": "eslint:recommended",
     "rules": {
-        // Override any settings from the "parent" configuration
-        "eqeqeq": 1
+        // specify different options
+        "no-cond-assign": ["error", "always"],
+        // turn off rules
+        "no-console": "off",
+        // turn on additional rules
+        "indent": ["error", 4],
+        "linebreak-style": ["error", "unix"],
+        "quotes": ["error", "double"],
+        "semi": ["error", "always"],
     }
 }
 ```
 
-Configurations may also be provided as an array, with additional files overriding any properties provided in the previous file. For example:
+### Extending a shareable configuration package
 
-```js
-{
-    "extends": [
-        "./node_modules/coding-standard/eslintDefaults.js",
-        // Override eslintDefaults.js
-        "./node_modules/coding-standard/.eslintrc-es6",
-        // Override .eslintrc-es6
-        "./node_modules/coding-standard/.eslintrc-jsx",
-    ],
+A [sharable configuration](../developer-guide/shareable-configs) is an npm package that exports a configuration object. Make sure the package has been installed to a directory where ESLint can require it.
 
+The `extends` property value can omit the `eslint-config-` prefix of the package name.
+
+The `eslint --init` command can create a configuration so you can extend a popular style guide (for example, `eslint-config-standard`).
+
+```json
+{
+    "extends": "standard",
     "rules": {
-        // Override any settings from the "parent" configuration
-        "eqeqeq": "warn"
+        "comma-dangle": ["error", "always"],
+        "no-empty": ["warn"]
     }
 }
 ```
 
-The extended configurations can also contain their own `extends`, resulting in recursive merging of the referenced configurations.
+### Extending the configuration from a plugin
 
-You can also extend configurations using shareable configuration packages. To do so, be sure to install the configuration package you want from npm and then use the package name, such as:
+A [plugin](../developer-guide/working-with-plugins) is an npm package that usually exports rules. Some plugins also export one or more named [configurations](../developer-guide/working-with-plugins#configs-in-plugins). Make sure the package has been installed to a directory where ESLint can require it.
 
-```js
-{
-    "extends": "eslint-config-myrules",
+The `plugins` [property value](#configuring-plugins) can omit the `eslint-plugin-` prefix of the package name.
+
+The `extends` property value can consist of:
 
+* `plugin:`
+* the package name (from which you can omit the prefix, for example, `react`)
+* `/`
+* the configuration name (for example, `recommended`)
+
+```json
+{
+    "plugins": [
+        "react"
+    ],
+    "extends": [
+        "eslint:recommended",
+        "plugin:react/recommended"
+    ],
     "rules": {
-        // Override any settings from the "parent" configuration
-        "eqeqeq": "warn"
+       "no-set-state": "off"
     }
 }
 ```
 
-In this example, the `eslint-config-myrules` package will be loaded as an object and used as the parent of this configuration.
+### Extending a configuration file
 
-**Note:** You can omit `eslint-config-` and ESLint will automatically insert it for you, similar to how plugins work. See [Shareable Configs](../developer-guide/shareable-configs) for more information.
+The `extends` property value can be an absolute or relative path to another [configuration file](#using-configuration-files).
 
-ESLint also supports extending configuration from plugins that provide configs:
+ESLint resolves a relative path to a "child" configuration file relative to the "parent" configuration file **unless** the "parent" file is in your home directory or a directory that isn't an ancestor to the directory in which ESLint is installed (either locally or globally). In those cases, ESLint resolves the relative path to the "child" file relative to the linted **project** directory (typically the current working directory).
 
-```js
+```json
 {
-    "extends": "plugin:eslint-plugin-myplugin/myConfig",
-
+    "extends": [
+        "./node_modules/coding-standard/eslintDefaults.js",
+        "./node_modules/coding-standard/.eslintrc-es6",
+        "./node_modules/coding-standard/.eslintrc-jsx"
+    ],
     "rules": {
-        // Override any settings from the "parent" configuration
         "eqeqeq": "warn"
     }
 }
 ```
 
-In this example, the `eslint-plugin-myplugin` package contains configuration named `default`.
+### Extending all core rules
 
-**Important:** When you are extending from the configuration bundled with plugins, you need to start with `plugin:` prefix as well as specify configuration name after the slash. You may optionally omit the `eslint-plugin-` prefix.
+The `extends` property value can be `"eslint:all"` to enable all core rules in the currently installed version of ESLint. The set of rules can change at any minor or major version of ESLint.
 
-**Note:** For configuration files in your home directory, or in any path that isn't an ancestor to the location of ESLint (either globally or locally), `extends` is resolved from the path of the project using ESLint (typically the current working directory) rather than relative to the file itself.
+```json
+{
+    "extends": "eslint:all",
+    "rules": {
+
+    }
+}
+```
 
 ## Comments in Configuration Files