docs: File extension named processor deprecation (#17362)

Matt Wilkinson · web-flow · commit 091f44e4c720 · 2023-07-28T11:05:24.000-04:00
diff --git a/docs/src/extend/custom-processors.md b/docs/src/extend/custom-processors.md
@@ -139,6 +139,10 @@ See [Specify a Processor](../use/configure/plugins#specify-a-processor) in the P
 
 ## File Extension-named Processor
 
+::: warning
+This feature is deprecated and only works in eslintrc-style configuration files. Flat config files do not automatically apply processors; you need to explicitly set the `processor` property.
+:::
+
 If a custom processor name starts with `.`, ESLint handles the processor as a **file extension-named processor**. ESLint applies the processor to files with that filename extension automatically. Users don't need to specify the file extension-named processors in their config files.
 
 For example:
diff --git a/docs/src/extend/plugins.md b/docs/src/extend/plugins.md
@@ -89,6 +89,10 @@ Plugin environments can define the following objects:
 
 ### Processors in Plugins
 
+::: warning
+File extension-named processors are deprecated and only work in eslintrc-style configuration files. Flat config files do not automatically apply processors; you need to explicitly set the `processor` property.
+:::
+
 You can add processors to plugins by including the processor functions in the `processors` key. For more information on defining custom processors, refer to [Custom Processors](custom-processors).
 
 ```js
diff --git a/docs/src/use/configure/migration-guide.md b/docs/src/use/configure/migration-guide.md
@@ -114,6 +114,83 @@ export default [
 ];
 ```
 
+### Processors
+
+In eslintrc files, processors had to be defined in a plugin, and then referenced by name in the configuration. Processors beginning with a dot indicated a [file extension-named processor](../../extend/custom-processors#file-extension-named-processor) which ESLint would automatically configure for that file extension.
+
+In flat config files, processors can still be referenced from plugins by their name, but they can now also be inserted directly into the configuration. Processors will _never_ be automatically configured, and must be explicitly set in the configuration.
+
+As an example with a custom plugin with processors:
+
+```javascript
+// node_modules/eslint-plugin-someplugin/index.js
+module.exports = {
+    processors: {
+        ".md": {
+            preprocess() {},
+            postprocess() {}
+        },
+        "someProcessor": {
+            preprocess() {},
+            postprocess() {}
+        }
+    }
+};
+```
+
+In eslintrc, you would configure as follows:
+
+```javascript
+// .eslintrc.js
+module.exports = {
+    plugins: ["someplugin"],
+    processor: "someplugin/someProcessor"
+};
+```
+
+ESLint would also automatically add the equivalent of the following:
+
+```javascript
+{
+     overrides: [{
+        files: ["**/*.md"],
+        processor: "someplugin/.md"
+     }]
+}
+```
+
+In flat config, the following are all valid ways to express the same:
+
+```javascript
+// eslint.config.js
+import somePlugin from "eslint-plugin-someplugin";
+
+export default [
+    {
+        plugins: { somePlugin },
+        processor: "somePlugin/someProcessor"
+    },
+    {
+        plugins: { somePlugin },
+        // We can embed the processor object in the config directly
+        processor: somePlugin.processors.someProcessor
+    },
+    {
+        // We don't need the plugin to be present in the config to use the processor directly
+        processor: somePlugin.processors.someProcessor
+    }
+];
+```
+
+Note that because the `.md` processor is _not_ automatically added by flat config, you also need to specify an extra configuration element:
+
+```javascript
+{
+    files: ["**/*.md"],
+    processor: somePlugin.processors[".md"]
+}
+```
+
 ### Glob-Based Configs
 
 By default, eslintrc files lint all files (except those covered by `.eslintignore`) in the directory in which they’re placed and its child directories. If you want to have different configurations for different file glob patterns, you can specify them in the `overrides` property.
