chore: polish

designs/2022-eslint-to-esm/README.md

@@ -1,6 +1,6 @@
 - Repo: eslint/eslint
 - Start Date: (2022-02-28)
-- RFC PR: (leave this empty, to be filled in later)
+- RFC PR: https://github.com/eslint/rfcs/pull/88
 - Authors: aladdin-add(weiran.zsd@outlook.com)
 
 # convert eslint codebase to esm
@@ -13,7 +13,7 @@ Convert the ESLint codebase to ESM and publish the ESM version.
 
 <!-- Why are we doing this? What use cases does it support? What is the expected
 outcome? -->
-The Node.js community has been written commonjs for a long time, the same goes for ESLint. But with ESM introduced in ES6 and officially supported by Node.js V12, more and more projects are moving to ESM. Not long ago, we had converted a few repos under the ESLint organization to ESM:
+The Node.js community has been written commonjs for a long time, the same goes for ESLint. But with ESM introduced in ES6 and officially supported by Node.js v12, more and more projects are moving to ESM. Not long ago, we had converted a few repos under the ESLint organization to ESM:
 * @eslint/eslintrc
 * espree
 * eslint-scope
@@ -61,40 +61,41 @@ There are two main ways to achieve this:
 Node.js ESM has a limitation: ESM cannot be required. Approach 2 provides a good compatibility for existing projects that rely on ESLint without requiring users to adopt ESM as well. In previous repos, dual-mode was mostly used (except for '@eslint/create-config').
 
 However, dual-mode also has a few disadvantages:
-1. dependencies. Some ESLint's dependencies have been (or will be) ESM-only, which means we won't be able to upgrade them if we continue to support CJS. For new dependencies, we cannot use them if they are ESM-only.
-2. Slower installation & larger installation volume, even though most users only use ESM, they still need to download CJS modules.
-3. Higher maintenance costs. You need to add build processes, test and publish ESM/CJS code.
+1. dependencies. Some ESLint's dependencies have been (or will be) esm-only, which means we won't be able to upgrade them if we continue to support CJS. For new dependencies, we cannot use them if they are esm-only.
+2. Slower installation & larger volume usage, even though most users only use ESM, they still need to download CJS modules.
+3. Higher maintenance costs. You need to add a build process, test and publish ESM/CJS code.
 4. The CLIs do not support dual-mode.
 
-Therefore, I would suggest that we eventually go with ESM-Only, but to give users more time to upgrade, as an intermediate state, we could use dual-mode in ESLint V9:
+In the (very) long run, I would suggest that we eventually go with esm-only, but to give users more time to upgrade, as an intermediate state, we could use dual-mode in ESLint v9:
 
 * eslint v9:
-    - ESLint CLI: esm only
-    - Node.js API: dual mode, 
-* eslint v10:
-    - ESLint CLI: esm only
-    - Node.js API: esm only 
+    - ESLint CLI: esm-only
+    - Node.js API: dual mode
+* eslint X (at the point when the majority of the ecosystem is ready to support it, likely to be v10/v11/...):
+    - ESLint CLI: esm-only
+    - Node.js API: esm-only
 
 ## Toolings esm supports
 
 * mocha ✅
 * proxyquire ❌
 * nyc ❌
-* eslint-plugin-node ❌(Not fully supported, but we could use a fork: eslint-plugin-n)
+* eslint-plugin-node ❗️(Not fully supported, but we could use a fork: `eslint-plugin-n`)
 
 ## Implementations
 1. ESLint v9
-* package.json + "type": "module"
+* package.json + `"type": "module"`
 * package.json exports
 * package.json engines >= Node.js v12
+* remove `"use strict"`
+* convert `"./foo"` to `"./foo/index.js"`
+* convert `"./foo"` to `"./foo.js"`
+* convert `require/module.exports` => `import/export`
+* esm toolings(`nyc` -> `c8`, `proxyquire` -> `esmock`)
+* cjs supports(build `dist/api.cjs` and `dist/use-at-your-own-risk.cjs` using rollup)
 * update docs to use esm
-* remove 'use strict'
-* convert './xxx' to './xxx/index.js'
-* convert './xxx' to './xxx.js'
-* esm toolings(nyc -> c8, proxyquire -> esmock)
-* cjs supports(build dist/api.js using rollup)
 
-2. ESLint v10
+2. ESLint X
 * remove package.json exports.cjs (use esm-only)
 * remove build process
 * upgrade blocked deps.
@@ -105,7 +106,7 @@ Therefore, I would suggest that we eventually go with ESM-Only, but to give user
     How will this RFC be documented? Does it need a formal announcement
     on the ESLint blog to explain the motivation?
 -->
-Yes. When ESLint V9 is released, it is recommended that users upgrade to ESM, CJS will no longer be supported in V10.
+Yes. When ESLint v9 is released, it is recommended to announce that users should upgrade to ESM, CJS may be no longer supported in future major versions.
 
 ## Drawbacks
 
@@ -130,9 +131,9 @@ Yes. When ESLint V9 is released, it is recommended that users upgrade to ESM, CJ
 -->
 
 1. For users of the ESLint CLI: there is no impact and users can write configuration files using ESM/CJS.
-2. For users of node.js API:
-* ESLint V9: Will support ESM/CJS, so there will be no compatibility issues for users.
-* ESLint V10: CJS will no longer be supported for users of the ESLint Node.js API. At this point developers can:
+2. For users of the Node.js API:
+* ESLint v9: Will support ESM/CJS, so there will be no compatibility issues for users.
+* ESLint X: CJS will no longer be supported. At this point developers can:
 
 a. convert to esm.
 ```diff
@@ -148,7 +149,7 @@ b. move to async.
 
 c. compile ESLint to CJS.
 
-d. stay eslint v9 util they can convert to esm.
+d. stay previous version util they can convert to esm.
 
 ## Alternatives
 
@@ -159,8 +160,10 @@ d. stay eslint v9 util they can convert to esm.
     projects have already implemented a similar feature.
 -->
 1. esm-only in eslint v9？
+TBD.
 
-2. dual-mode??
+2. cjs only??
+TBD.
 
 ## Open Questions