docs: update README for v4

README.md

@@ -32,18 +32,26 @@
 
 You'll first need to install [ESLint](http://eslint.org):
 
-```
-$ npm i eslint --save-dev
+```shell
+$ npm install --save-dev eslint
+# or
+$ yarn add --dev eslint
 ```
 
 Next, install `eslint-plugin-testing-library`:
 
-```
-$ npm install eslint-plugin-testing-library --save-dev
+```shell
+$ npm install --save-dev eslint-plugin-testing-library
+# or
+$ yarn add --dev eslint-plugin-testing-library
 ```
 
 **Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `eslint-plugin-testing-library` globally.
 
+## Migrating to v4
+
+You can find [here a detailed guide for migrating `eslint-plugin-testing-library` to v4](docs/migrating-to-v4-guide.md).
+
 ## Usage
 
 Add `testing-library` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:
@@ -54,22 +62,37 @@ Add `testing-library` to the plugins section of your `.eslintrc` configuration f
 }
 ```
 
-Then configure the rules you want to use under the rules section.
+Then configure the rules you want to use within `rules` property of your `.eslintrc`:
 
 ```json
 {
   "rules": {
     "testing-library/await-async-query": "error",
     "testing-library/no-await-sync-query": "error",
-    "testing-library/no-debug": "warn"
+    "testing-library/no-debug": "warn",
+    "testing-library/no-dom-import": "off"
   }
 }
 ```
 
 ## Shareable configurations
 
 This plugin exports several recommended configurations that enforce good practices for specific Testing Library packages.
-You can find more info about enabled rules in the [Supported Rules section](#supported-rules) within the `Configurations` column.
+You can find more info about enabled rules in the [Supported Rules section](#supported-rules), under the `Configurations` column.
+
+Since each one of these configurations is aimed at a particular Testing Library package, they are not extendable between them, so you should use only one of them at once per `eslintrc` file. For example, if you want to enable recommended configuration for React, you don't need to combine it somehow with DOM one:
+
+```json
+// ❌ Don't do this
+{
+  "extends": ["plugin:testing-library/dom", "plugin:testing-library/react"]
+}
+
+// ✅ Do just this instead
+{
+  "extends": ["plugin:testing-library/react"]
+}
+```
 
 ### DOM Testing Library
 
@@ -172,6 +195,42 @@ To enable this configuration use the `extends` property in your
 [react-badge]: https://img.shields.io/badge/-React-black?style=flat-square&logo=react&logoColor=white&labelColor=61DAFB&color=black
 [vue-badge]: https://img.shields.io/badge/-Vue-black?style=flat-square&logo=vue.js&logoColor=white&labelColor=4FC08D&color=black
 
+## Shared Settings
+
+There are some configuration options available that will be shared across all the plugin rules. This is achieved using [ESLint Shared Settings](https://eslint.org/docs/user-guide/configuring/configuration-files#adding-shared-settings). These Shared Settings are meant to be used if you need to restrict the Aggressive Reporting mechanism, which is an out of the box advanced feature to lint Testing Library usages in a simpler way for most of the users. **So please before configuring any of these settings**, read more about [the advantages of `eslint-plugin-testing-library` Aggressive Reporting mechanism](docs/migrating-to-v4-guide.md#aggressive-reporting), and [how it's affected by these settings](docs/migrating-to-v4-guide.md#shared-settings).
+
+If you are sure about configuring the settings, these are the options available:
+
+### `testing-library/utils-module`
+
+The name of your custom utility file from where you re-export everything from Testing Library package.
+
+```json
+// .eslintrc
+{
+  "settings": {
+    "testing-library/utils-module": "my-custom-test-utility-file"
+  }
+}
+```
+
+[You can find more details here](docs/migrating-to-v4-guide.md#testing-libraryutils-module).
+
+### `testing-library/custom-renders`
+
+A list of function names that are valid as Testing Library custom renders. Relates to [Aggressive Reporting - Renders](docs/migrating-to-v4-guide.md#renders)
+
+```json
+// .eslintrc
+{
+  "settings": {
+    "testing-library/custom-renders": ["display", "renderWithProviders"]
+  }
+}
+```
+
+[You can find more details here](docs/migrating-to-v4-guide.md#testing-librarycustom-renders).
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

docs/migrating-to-v4-guide.md

@@ -153,13 +153,13 @@ _You can find the motivation behind this behavior on [this issue comment](https:
 
 By default, `eslint-plugin-testing-library` v4 won't check from which module are the utils imported. This means it doesn't matter if you are importing the utils from `@testing-library/*`, `test-utils` or `whatever`.
 
-There is a new Shared Setting to restrict this scope though: [`utils-module`](#utils-module). By using this setting, only utils imported from `@testing-library/*` packages, or the custom one indicated in this setting would be reported.
+There is a new Shared Setting to restrict this scope though: [`utils-module`](#testing-libraryutils-module). By using this setting, only utils imported from `@testing-library/*` packages, or the custom one indicated in this setting would be reported.
 
 ### Renders
 
 By default, `eslint-plugin-testing-library` v4 will assume that all methods which names contain "render" should be reported. This means it doesn't matter if you are rendering your elements for testing using `render`, `customRender` or `renderWithRedux`.
 
-There is a new Shared Setting to restrict this scope though: [`custom-renders`](#custom-renders). By using this setting, only methods strictly named `render` or as one of the indicated Custom Renders would be reported.
+There is a new Shared Setting to restrict this scope though: [`custom-renders`](#testing-librarycustom-renders). By using this setting, only methods strictly named `render` or as one of the indicated Custom Renders would be reported.
 
 ### Queries
 
@@ -175,24 +175,54 @@ To avoid collision with settings from other ESLint plugins, all the properties f
 
 ⚠️ **Please be aware of using these settings will disable part of [Aggressive Reporting](#aggressive-reporting).**
 
-### `utils-module`
+### `testing-library/utils-module`
 
-Relates to [Aggressive Reporting - Imports](#imports). This setting (just a string) allows you to indicate which is the only Custom Module you'd like to be reported by `eslint-plugin-testing-library`.
+The name of your custom utility file from where you re-export everything from Testing Library package. Relates to [Aggressive Reporting - Imports](#imports).
 
 ```json
 // .eslintrc
 {
   "settings": {
-    "testing-library/utils-module": "my-custom-test-utils"
+    "testing-library/utils-module": "my-custom-test-utility-file"
   }
 }
 ```
 
-The previous setting example would force `eslint-plugin-testing-library` to only report Testing Library utils coming from `@testing-library/*` package or `my-custom-test-utils`, silencing potential errors for utils imported from somewhere else.
+Enabling this setting, you'll restrict the errors reported by the plugin to only those utils being imported from this custom utility file, or some `@testing-library/*` package. The previous setting example would cause:
 
-### `custom-renders`
+```javascript
+import { waitFor } from '@testing-library/react';
+
+test('testing-library/utils-module setting example', () => {
+  // ✅ this would be reported since this invalid usage of an util
+  // is imported from `@testing-library/*` package
+  waitFor(/* some invalid usage to be reported */);
+});
+```
+
+```javascript
+import { waitFor } from '../my-custom-test-utility-file';
+
+test('testing-library/utils-module setting example', () => {
+  // ✅ this would be reported since this invalid usage of an util
+  // is imported from specified custom utility file.
+  waitFor(/* some invalid usage to be reported */);
+});
+```
 
-Relates to [Aggressive Reporting - Renders](#renders). This setting (array of strings) allows you to indicate which are the only Custom Renders you'd like to be reported by `eslint-plugin-testing-library`.
+```javascript
+import { waitFor } from '../somewhere-else';
+
+test('testing-library/utils-module setting example', () => {
+  // ❌ this would NOT be reported since this invalid usage of an util
+  // is NOT imported from either `@testing-library/*` package or specified custom utility file.
+  waitFor(/* some invalid usage to be reported */);
+});
+```
+
+### `testing-library/custom-renders`
+
+A list of function names that are valid as Testing Library custom renders. Relates to [Aggressive Reporting - Renders](#renders)
 
 ```json
 // .eslintrc
@@ -203,4 +233,39 @@ Relates to [Aggressive Reporting - Renders](#renders). This setting (array of st
 }
 ```
 
-The previous setting example would force `eslint-plugin-testing-library` to only report Testing Library renders named `render` (built-in one is always included), `display` and `renderWithProviders`, silencing potential errors for others custom renders.
+Enabling this setting, you'll restrict the errors reported by the plugin related to `render` somehow to only those functions sharing a name with one of the elements of that list, or built-in `render`. The previous setting example would cause:
+
+```javascript
+import {
+  render,
+  display,
+  renderWithProviders,
+  renderWithRedux,
+} from 'test-utils';
+import Component from 'somewhere';
+
+const setupA = () => renderWithProviders(<Component />);
+const setupB = () => renderWithRedux(<Component />);
+
+test('testing-library/custom-renders setting example', () => {
+  // ✅ this would be reported since `render` is a built-in Testing Library util
+  const invalidUsage = render(<Component />);
+
+  // ✅ this would be reported since `display` has been set as `custom-render`
+  const invalidUsage = display(<Component />);
+
+  // ✅ this would be reported since `renderWithProviders` has been set as `custom-render`
+  const invalidUsage = renderWithProviders(<Component />);
+
+  // ❌ this would NOT be reported since `renderWithRedux` isn't a `custom-render` or built-in one
+  const invalidUsage = renderWithRedux(<Component />);
+
+  // ✅ this would be reported since it wraps `renderWithProviders`,
+  // which has been set as `custom-render`
+  const invalidUsage = setupA(<Component />);
+
+  // ❌ this would NOT be reported since it wraps `renderWithRedux`,
+  // which isn't a `custom-render` or built-in one
+  const invalidUsage = setupB(<Component />);
+});
+```