Merge pull request #304 from nodejs/update-docs

Update documents per current status

README.md

@@ -15,7 +15,10 @@ Work includes:
 
 ## Current Efforts
 
-The team is working on a new implementation to potentially replace the `--experimental-modules` implementation in current shipping Node. The new implementation is in progress in the [ecmascript-modules](https://github.com/nodejs/ecmascript-modules) repo, and a road map of its development is [here](./doc/plan-for-new-modules-implementation.md).
+> ### [Current Plan for `--experimental-modules`](./doc/plan-for-new-modules-implementation.md)
+
+The team is working on a new implementation that replaces the Node.js 8 through 11 `--experimental-modules` implementation starting in Node.js 12. The new implementation is in progress in the [ecmascript-modules](https://github.com/nodejs/ecmascript-modules) repo. A road map of its development is [here](./doc/plan-for-new-modules-implementation.md).
+
 
 ## Features
 

doc/announcement.md

@@ -38,7 +38,7 @@ And the new version of `--experimental-modules` adds:
 
 We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.
 
-The new `--experimental-modules` provides two ways: a `"type"` field in `package.json` and a `--type` flag. Their naming was inspired by browsers’ `<script type="module">`.
+The new `--experimental-modules` provides two ways: a `"type"` field in `package.json` and an `--entry-type` flag. Their naming was inspired by browsers’ `<script type="module">`.
 
 ### `package.json` `"type"` field
 
@@ -48,13 +48,15 @@ If some of your project’s files use CommonJS and you can’t convert your enti
 
 For any file that Node.js tries to load, it will look for a `package.json` in that file’s folder, then that file’s parent folder and so on upwards until it reaches the root of the volume. This is similar to [how Babel searches for `.babelrc` files](https://babeljs.io/docs/en/config-files#file-relative-configuration). This new approach allows Node.js to use `package.json` for package-level metadata and configuration, similar to how it is already used by Babel and other tools.
 
-### `--type` flag
+### `--entry-type` flag
 
-Use `--type=module`, or the shorthand `-m`, to run a `.js` file as an ES module.
+Use `--entry-type=module` to run a `.js` file as an ES module.
 
-When running a file, e.g. `node --experimental-modules --type=module main.js`, Node.js follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--type` flag. The `--type` flag can be `--type=module` (or `-m`) or `--type=commonjs`. You can also set this flag in `NODE_OPTIONS` if you’d like to change how Node.js behaves systemwide.
+When running a file, e.g. `node --experimental-modules --entry-type=module main.js`, Node.js follows an algorithm to determine if it should load the file as CommonJS or as an ES module. First it looks for an explicit file extension (`.mjs` or `.cjs`); then it looks for a `"type"` field in the nearest parent `package.json`; and finally it looks at the `--entry-type` flag. The `--entry-type` flag can be `--entry-type=module` or `--entry-type=commonjs`.
 
-This flag provides a way to support ES module syntax for input via `--eval`, `--print`, or `STDIN`.
+Note that setting the type of a file via `--entry-type` does _not_ set the type for any files that that file may `import`; you probably want to add a `package.json` with a `"type"` field to define the type for a folder of files.
+
+This flag provides a way to support ES module syntax for input via `--eval`, `--print`, or `STDIN`; and for loose single `.js` and extensionless files outside of any package or project.
 
 ## `.cjs` extension
 
@@ -90,7 +92,7 @@ Currently it is not possible to create a package that can be used via both `requ
 
 All of the above is shipping as part of `--experimental-modules` in Node.js 12. On our [road map](https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md) for potential improvements before the `--experimental-modules` flag is hopefully dropped in October 2019, when Node.js 12 reaches LTS status:
 
-**Loaders features.** Loaders are being further developed to support process isolation, multiple loaders, and multi-Realm support with lower-level hooks. The `--loader` API will still change considerably before this is unflagged.
+- **Loaders features.** Loaders are being further developed to support process isolation, multiple loaders, and multi-Realm support with lower-level hooks. The `--loader` API will still change considerably before this is unflagged.
 
 - **Dual CommonJS/ES module packages.** We want to provide a standard way for package authors to publish a package that can be both `require`d into CommonJS or `import`ed into an ES module.
 

doc/plan-for-new-modules-implementation.md

@@ -7,13 +7,14 @@ This document outlines the plan for building a new implementation to support ECM
 * **Phase 1** adds the “minimal kernel,” features that the modules working group felt would likely appear in any potential new ES modules implementation.
 
 * **Phase 2** fleshes out the implementation with enough functionality that it should be useful to average users as a minimum viable product.
-  - At the completion of Phase 2, the old `--experimental-modules` implementation is replaced with this new one (still behind the `--experimental-modules` flag). The goal is to “upstream” the new implementation with the release of Node 12, in April 2019.
+
+  - At the completion of Phase 2, the old `--experimental-modules` implementation was [replaced](https://github.com/nodejs/node/pull/26745) with this new one (still behind the `--experimental-modules` flag). It will be released as part of Node 12, in April 2019.
 
 * **Phase 3** improves user experience and extends the MVP.
 
   - At the completion of Phase 3, the new implementation’s experimental flag is dropped. The goal is to “release” (drop the `--experimental-modules` flag) by when Node 12 starts LTS in October 2019.
 
-The effort is currently in **Phase 2**.
+The effort is currently in **[Phase 3](#phase-3-path-to-stability-removing---experimental-modules-flag)**.
 
 At every phase, the following standards must be maintained:
 
@@ -66,7 +67,7 @@ The “minimal kernel” consists of features that the @nodejs/modules group hav
 
 ## Phase 2: Minimum Viable Product: Required to Upstream
 
-Phase 2 fleshes out the implementation with enough functionality that it should be useful to average users as a minimum viable product. At the completion of Phase 2, the old `--experimental-modules` implementation is replaced with this new one (still behind the `--experimental-modules` flag).
+Phase 2 fleshes out the implementation with enough functionality that it should be useful to average users as a minimum viable product. At the completion of Phase 2, the old `--experimental-modules` implementation was replaced with this new one (still behind the `--experimental-modules` flag).
 
 * Define semantics for importing a package entry point, e.g. `import _ from 'lodash'`
   - Proposal: [“File Specifier Resolution” proposal](https://github.com/GeoffreyBooth/node-import-file-specifier-resolution-proposal) covers bare module specifier resolution of CommonJS packages.
@@ -79,11 +80,13 @@ Phase 2 fleshes out the implementation with enough functionality that it should
 * Define semantics for enabling ESM treatment of source code loaded via `--eval`, STDIN, and extensionless files (both with and without shebang lines).
   - Proposal: [“Entry Points Proposal”](https://github.com/geoffreybooth/node-esm-entry-points-proposal) covers non-file forms of input as well as adding `--type` flag for controlling file-based input.
   - Landed in https://github.com/nodejs/ecmascript-modules/pull/32.
+  - Renamed to `--entry-type` as part of upstream PR to Node.js core.
 
-* File extension and directory index searching in ESM, behind its own flag.
+* File extension and directory index searching in ESM, behind its own flag, `--es-module-specifier-resolution`.
   - See https://github.com/nodejs/modules/issues/268.
-  - Per 2019-03-04 meeting, searching will be disabled by default in ESM but enabled via a flag; and the flag will be neutral as to which state the feature should take (similar to `--type=commonjs` / `--type=module`, where the former is currently a noop because it’s the default; but if the default changes someday, the latter would become the noop).
+  - Landed in https://github.com/nodejs/ecmascript-modules/pull/48.
 
+The work through the end of Phase 2 landed in Node.js `master` as part of https://github.com/nodejs/node/pull/26745.
 
 ## Phase 3: Path to Stability: Removing `--experimental-modules` Flag
 
@@ -94,9 +97,10 @@ Phase 3 improves user experience and extends the MVP. Phase 3 is malleable based
 * A loaders solution that supports all items in the [features list in our README](https://github.com/nodejs/modules/#features).
   - Should loaders be per package, per application or either?
 
-* Dual CommonJS/ESM packages: Either support packages that can both be `require`d as CommonJS and `import`ed as ESM; or decide to specifically not support dual CommonJS/ESM packages.
-  - Proposal: https://github.com/nodejs/modules/issues/273.
-  - PR: https://github.com/nodejs/ecmascript-modules/pull/41.
+* Dual CommonJS/ESM packages: Either support packages with both CommonJS and ESM sources that can be used in either environment; or decide to specifically not support dual CommonJS/ESM packages.
+  - Proposal 1: https://github.com/nodejs/modules/issues/273.
+  - PR for Proposal 1: https://github.com/nodejs/ecmascript-modules/pull/41.
+  - Proposal 2: https://github.com/nodejs/modules/issues/299.
 
 * Better mechanism for creating `require` function.
   - See [https://gist.github.com/SMotaal/e73c12bd801d78a3108fa30ecd303676](https://gist.github.com/SMotaal/e73c12bd801d78a3108fa30ecd303676).
@@ -107,9 +111,14 @@ Phase 3 improves user experience and extends the MVP. Phase 3 is malleable based
 
 * Automatic entry point module type detection.
   - Proposal: [“Entry Points Proposal”](https://github.com/geoffreybooth/node-esm-entry-points-proposal) includes `--type=auto` flag for running `.js` files in either ESM or CommonJS based on which module system is detected.
+  - PR: https://github.com/nodejs/ecmascript-modules/pull/55.
 
 ### Needs Consensus
 
+* Determine the name and functionality behind command-line flag(s) for specifying CommonJS or ESM.
+  - See https://github.com/nodejs/modules/issues/300.
+  - Apply to non-file inputs only? Entry point only? Package scope/mirror `package.json` `"type"`?
+
 * Finalize support for (or removal of) `import` of CommonJS files and packages.
   - See https://github.com/nodejs/modules/issues/264.
   - Defaults only or named exports? Behind a flag or not?