From 565ba5dd014c630c403838b26ae6dcf04d5b72b7 Mon Sep 17 00:00:00 2001
From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com>
Date: Wed, 8 Nov 2023 22:58:27 +0900
Subject: [PATCH] Update migration guide

---
 docs/migration-guide/to-16.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/migration-guide/to-16.md b/docs/migration-guide/to-16.md
index b185a0721a..361e314a6e 100644
--- a/docs/migration-guide/to-16.md
+++ b/docs/migration-guide/to-16.md
@@ -4,6 +4,7 @@ This release contains breaking changes. We've:
 
 - removed deprecated stylistic rules
 - removed support for Node.js less than 18.12.0
+- changed `.js` extension to `.mjs` and `.cjs`
 - changed Node.js API returned resolved object
 - changed CLI to print problems to stderr
 - changed CLI exit code for flag errors
@@ -20,6 +21,31 @@ Node.js 14 and 16 have reached end-of-life. We've removed support for them so th
 
 You should use the 18.12.0 or higher versions of Node.js.
 
+## Changed `.js` extensions to `.mjs` and `.cjs`
+
+We've changed the file extension `.js` to `.mjs` and `.cjs` to support ESM and CJS.
+
+You should modify your code if using `.js` for `import` or `require`. For example:
+
+ESM:
+
+```diff js
+-import('stylelint/lib/utils/typeGuards.js');
++import('stylelint/lib/utils/typeGuards.mjs');
+```
+
+CJS:
+
+```diff js
+-require('stylelint/lib/utils/typeGuards.js');
++require('stylelint/lib/utils/typeGuards.cjs');
+```
+
+> [!WARNING]
+> We've strongly recommended copying the internal utilities to your project instead of importing them.
+> You can unsafely continue to `import` or `require` the files, but we will disallow access to them in the next major release.
+> See also [`stylelint.utils`](../developer-guide/plugins.md#stylelintutils) in the developer guide.
+
 ## Changed Node.js API returned resolved object
 
 We've changed the resolved object of the Promise returned by `stylelint.lint()` so that: