diff --git a/docs/src/use/migrate-to-9.0.0.md b/docs/src/use/migrate-to-9.0.0.md
index 5f57a5d01f7..ba4e0ae81a3 100644
--- a/docs/src/use/migrate-to-9.0.0.md
+++ b/docs/src/use/migrate-to-9.0.0.md
@@ -22,15 +22,15 @@ The lists below are ordered roughly by the number of users each change is expect
* [Removed `require-jsdoc` and `valid-jsdoc` rules](#remove-jsdoc-rules)
* [`eslint:recommended` has been updated](#eslint-recommended)
* [`--quiet` no longer runs rules set to `"warn"`](#quiet-warn)
+* [`--output-file` now writes a file to disk even with an empty output](#output-file)
* [Change in behavior when no patterns are passed to CLI](#cli-empty-patterns)
* [`/* eslint */` comments with only severity now retain options from the config file](#eslint-comment-options)
+* [Stricter `/* exported */` parsing](#exported-parsing)
* [`no-constructor-return` and `no-sequences` rule schemas are stricter](#stricter-rule-schemas)
* [New checks in `no-implicit-coercion` by default](#no-implicit-coercion)
* [Case-sensitive flags in `no-invalid-regexp`](#no-invalid-regexp)
-* [Stricter `/* exported */` parsing](#exported-parsing)
-* [`"eslint:recommended"` and `"eslint:all"` strings no longer accepted in flat config](#string-config)
* [`varsIgnorePattern` option of `no-unused-vars` no longer applies to catch arguments](#vars-ignore-pattern)
-* [`--output-file` now writes a file to disk even with an empty output](#output-file)
+* [`"eslint:recommended"` and `"eslint:all"` strings no longer accepted in flat config](#string-config)
### Breaking changes for plugin developers
@@ -127,6 +127,14 @@ If `--max-warnings` is used then `--quiet` will not suppress the execution of ru
**Related issue(s):** [#16450](https://github.com/eslint/eslint/issues/16450)
+## `--output-file` now writes a file to disk even with an empty output
+
+Prior to ESLint v9.0.0, the `--output-file` flag would skip writing a file to disk if the output was empty. However, in ESLint v9.0.0, `--output-file` now consistently writes a file to disk, even when the output is empty. This update ensures a more consistent and reliable behavior for `--output-file`.
+
+**To address:** Review your usage of the `--output-file` flag, especially if your processes depend on the file's presence or absence based on output content. If necessary, update your scripts or configurations to accommodate this change.
+
+**Related Issues(s):** [#17660](https://github.com/eslint/eslint/issues/17660)
+
## Change in behavior when no patterns are passed to CLI
Prior to ESLint v9.0.0, running the ESLint CLI without any file or directory patterns would result in no files being linted and would exit with code 0. This was confusing because it wasn't clear that nothing had actually happened. In ESLint v9.0.0, this behavior has been updated:
@@ -178,6 +186,30 @@ Note that this change only affects cases where the same rule is configured in th
**Related issue(s):** [#17381](https://github.com/eslint/eslint/issues/17381)
+## Stricter `/* exported */` parsing
+
+Prior to ESLint v9.0.0, the `/* exported */` directive incorrectly allowed the following syntax:
+
+```js
+/* exported foo: true, bar: false */
+
+// and
+
+/* exported foo bar */
+```
+
+The `true` and `false` in this example had no effect on ESLint's behavior, and in fact, was a parsing bug.
+
+In ESLint v9.0.0, any `/* exported */` variables followed by a colon and value will be ignored as invalid.
+
+**To address:** Update any `/* exported */` directives to eliminate the colons and subsequent values, and ensure there are commas between variable names such as:
+
+```js
+/* exported foo, bar */
+```
+
+**Related issue(s):** [#17622](https://github.com/eslint/eslint/issues/17622)
+
## `no-constructor-return` and `no-sequences` rule schemas are stricter
In previous versions of ESLint, `no-constructor-return` and `no-sequences` rules were mistakenly accepting invalid options.
@@ -229,29 +261,24 @@ In ESLint v9.0.0, the option `allowConstructorFlags` is now case-sensitive.
**Related issue(s):** [#16574](https://github.com/eslint/eslint/issues/16574)
-## Stricter `/* exported */` parsing
+## `varsIgnorePattern` option of `no-unused-vars` no longer applies to catch arguments
-Prior to ESLint v9.0.0, the `/* exported */` directive incorrectly allowed the following syntax:
+In previous versions of ESLint, the `varsIgnorePattern` option of `no-unused-vars` incorrectly ignored errors specified in a `catch` clause. In ESLint v9.0.0, `varsIgnorePattern` no longer applies to errors in `catch` clauses. For example:
```js
-/* exported foo: true, bar: false */
+/*eslint no-unused-vars: ["error", { "caughtErrors": "all", "varsIgnorePattern": "^err" }]*/
-// and
+try {
+ //...
+} catch (err) { // 'err' will be reported.
+ console.error("errors");
+}
-/* exported foo bar */
```
-The `true` and `false` in this example had no effect on ESLint's behavior, and in fact, was a parsing bug.
-
-In ESLint v9.0.0, any `/* exported */` variables followed by a colon and value will be ignored as invalid.
-
-**To address:** Update any `/* exported */` directives to eliminate the colons and subsequent values, and ensure there are commas between variable names such as:
-
-```js
-/* exported foo, bar */
-```
+**To address:** If you want to specify ignore patterns for `catch` clause variable names, use the `caughtErrorsIgnorePattern` option in addition to `varsIgnorePattern`.
-**Related issue(s):** [#17622](https://github.com/eslint/eslint/issues/17622)
+**Related issue(s):** [#17540](https://github.com/eslint/eslint/issues/17540)
## `"eslint:recommended"` and `"eslint:all"` no longer accepted in flat config
@@ -281,33 +308,6 @@ export default [
**Related issue(s):** [#17488](https://github.com/eslint/eslint/issues/17488)
-## `varsIgnorePattern` option of `no-unused-vars` no longer applies to catch arguments
-
-In previous versions of ESLint, the `varsIgnorePattern` option of `no-unused-vars` incorrectly ignored errors specified in a `catch` clause. In ESLint v9.0.0, `varsIgnorePattern` no longer applies to errors in `catch` clauses. For example:
-
-```js
-/*eslint no-unused-vars: ["error", { "caughtErrors": "all", "varsIgnorePattern": "^err" }]*/
-
-try {
- //...
-} catch (err) { // 'err' will be reported.
- console.error("errors");
-}
-
-```
-
-**To address:** If you want to specify ignore patterns for `catch` clause variable names, use the `caughtErrorsIgnorePattern` option in addition to `varsIgnorePattern`.
-
-**Related issue(s):** [#17540](https://github.com/eslint/eslint/issues/17540)
-
-## `--output-file` now writes a file to disk even with an empty output
-
-Prior to ESLint v9.0.0, the `--output-file` flag would skip writing a file to disk if the output was empty. However, in ESLint v9.0.0, `--output-file` now consistently writes a file to disk, even when the output is empty. This update ensures a more consistent and reliable behavior for `--output-file`.
-
-**To address:** Review your usage of the `--output-file` flag, especially if your processes depend on the file's presence or absence based on output content. If necessary, update your scripts or configurations to accommodate this change.
-
-**Related Issues(s):** [#17660](https://github.com/eslint/eslint/issues/17660)
-
## Removed multiple `context` methods
ESLint v9.0.0 removes multiple deprecated methods from the `context` object and moves them onto the `SourceCode` object: