From f3e505bc2bc87f28aa10267aed8172f08c7d9c9a Mon Sep 17 00:00:00 2001
From: minervabot <53988640+minervabot@users.noreply.github.com>
Date: Mon, 2 Jan 2023 02:28:07 -0700
Subject: [PATCH] [Docs] `order`: Add a quick note on how unbound imports and
 --fix

Having unbound imports mixed among the bound ones causes unexpected and incorrect seeming results. I spent several hours trying to fix this problem only to find it was well known!
---
 CHANGELOG.md        |  3 +++
 docs/rules/order.md | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7ad93fbd3..77c908dc3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 - [`no-unused-modules`]: add console message to help debug [#2866]
 - [Refactor] `ExportMap`: make procedures static instead of monkeypatching exportmap ([#2982], thanks [@soryy708])
 - [Refactor] `ExportMap`: separate ExportMap instance from its builder logic ([#2985], thanks [@soryy708])
+- [Docs] `order`: Add a quick note on how unbound imports and --fix ([#2640], thanks [@minervabot])
 
 ## [2.29.1] - 2023-12-14
 
@@ -1130,6 +1131,7 @@ for info on changes for earlier releases.
 [#2735]: https://github.com/import-js/eslint-plugin-import/pull/2735
 [#2699]: https://github.com/import-js/eslint-plugin-import/pull/2699
 [#2664]: https://github.com/import-js/eslint-plugin-import/pull/2664
+[#2640]: https://github.com/import-js/eslint-plugin-import/pull/2640
 [#2613]: https://github.com/import-js/eslint-plugin-import/pull/2613
 [#2608]: https://github.com/import-js/eslint-plugin-import/pull/2608
 [#2605]: https://github.com/import-js/eslint-plugin-import/pull/2605
@@ -1846,6 +1848,7 @@ for info on changes for earlier releases.
 [@mgwalker]: https://github.com/mgwalker
 [@mhmadhamster]: https://github.com/MhMadHamster
 [@MikeyBeLike]: https://github.com/MikeyBeLike
+[@minervabot]: https://github.com/minervabot
 [@mpint]: https://github.com/mpint
 [@mplewis]: https://github.com/mplewis
 [@mrmckeb]: https://github.com/mrmckeb
diff --git a/docs/rules/order.md b/docs/rules/order.md
index 2335699e6..24692f2d2 100644
--- a/docs/rules/order.md
+++ b/docs/rules/order.md
@@ -77,6 +77,25 @@ import foo from './foo';
 var path = require('path');
 ```
 
+## Limitations of `--fix`
+
+Unbound imports are assumed to have side effects, and will never be moved/reordered. This can cause other imports to get "stuck" around them, and the fix to fail.
+
+```javascript
+import b from 'b'
+import 'format.css';  // This will prevent --fix from working.
+import a from 'a'
+```
+
+As a workaround, move unbound imports to be entirely above or below bound ones.
+
+```javascript
+import 'format1.css';  // OK
+import b from 'b'
+import a from 'a'
+import 'format2.css';  // OK
+```
+
 ## Options
 
 This rule supports the following options: