Rewrite readme #482
Rewrite readme #482
Conversation
arch: improve archived documents
README.md
Outdated
| * Browser equivalence ([#133](https://github.com/nodejs/modules/issues/133)) | ||
| * Don’t break CommonJS ([#112](https://github.com/nodejs/modules/issues/112)) | ||
| * No refactoring ([#87](https://github.com/nodejs/modules/issues/87)) | ||
| CommonJS is not statically analyzable (that’s one of the primary benefits of `import`/`export` syntax) and therefore the exported names cannot be known to Node.js simply by parsing JavaScript source code: the code needs to actually be evaluated in order for Node.js to discover what identifiers get attached to `module.exports` for each file. But evaluating the CommonJS code in what the ECMAScript Modules spec calls the “linking” phase (when the module graph is determined) is not permitted; this would mean that CommonJS code is evaluated early, before any ES module code, whereas the spec defines the order of modules’ evaluation based on the depth of imports. This early evaluation presents other issues in that if a dependency gets converted from CommonJS to ESM, its order of evaluation would change in the user’s application; and early evaluation might trigger side effects if reading the values from `module.exports` were getters or proxies. |
There was a problem hiding this comment.
and early evaluation might trigger side effects if reading the values from
module.exportswere getters or proxies.
This is a separate point that isn't about early evaluation. This is specifically about Object.values(module.exports) having side effects, whereas those side effects would never otherwise trigger.
There was a problem hiding this comment.
Can you please rephrase the text so that it’s correct? Maybe offer a suggestion?
There was a problem hiding this comment.
| CommonJS is not statically analyzable (that’s one of the primary benefits of `import`/`export` syntax) and therefore the exported names cannot be known to Node.js simply by parsing JavaScript source code: the code needs to actually be evaluated in order for Node.js to discover what identifiers get attached to `module.exports` for each file. But evaluating the CommonJS code in what the ECMAScript Modules spec calls the “linking” phase (when the module graph is determined) is not permitted; this would mean that CommonJS code is evaluated early, before any ES module code, whereas the spec defines the order of modules’ evaluation based on the depth of imports. This early evaluation presents other issues in that if a dependency gets converted from CommonJS to ESM, its order of evaluation would change in the user’s application; and early evaluation might trigger side effects if reading the values from `module.exports` were getters or proxies. | |
| CommonJS is not statically analyzable (that’s one of the primary benefits of `import`/`export` syntax) and therefore the exported names cannot be known to Node.js simply by parsing JavaScript source code: the code needs to actually be evaluated in order for Node.js to discover what identifiers get attached to `module.exports` for each file. But evaluating the CommonJS code in what the ECMAScript Modules spec calls the “linking” phase (when the module graph is determined) is not permitted; this would mean that CommonJS code is evaluated early, before any ES module code, whereas the spec defines the order of modules’ evaluation based on the depth of imports. This early evaluation presents other issues in that if a dependency gets converted from CommonJS to ESM, its order of evaluation would change in the user’s application. | |
| In addition to these issues of execution ordering, there is also the problem of reading those named exports. The way ES modules define their exports still means we would be applying an `Object.values(module.exports)` for all CommonJS modules as soon as they finish executing, in order to populate the ES module exports. This can lead to a number of problems: | |
| * The triggering of getters and proxies (eg for dynamic generation / deprecation warnings) can throw errors or cause unwanted side effects. | |
| * New exports added to `module.exports` after this time would never be available as named exports. | |
| * Mutations to `module.exports` cannot be kept live with the ES module exports, unless we turn all CommonJS `module.exports` into a proxy. This in turn could have backwards compatibility issues. |
README.md
Outdated
| * Loader hooks | ||
| * ESM and CommonJS interoperability | ||
| * Node.js and browser interoperability | ||
| * VM modules implementation | ||
|
|
||
| ## Current Efforts |
There was a problem hiding this comment.
It would be nice if we could include a Current Status section before all the experimental / new stuff, that captures what the group has already achieved.
There was a problem hiding this comment.
It sounds like a good idea, I'm just a bit unclear on what you have in mind. What would the different statuses be? Here's an idea I had for displaying different statuses of various features, it might be similar to what you're after.
There was a problem hiding this comment.
The overall content is great, I'm just thinking perhaps we need to separate the README from the history.md from the roadmap.md. We also don't want to risk the README content going stale again too.
If we instead have more introductory information about the group and what it is and what it's done in the README, linking off to the other sections rather.
If we're looking to make specific advisories to users about the implementation status, perhaps the better place for that is the modules docs?
Wherever we put the “this is what we’re working on now” content, it will gradually become stale. I think it belongs near the top of the README, because that’s what the general public is coming to our repo for. That’s the information they can’t get anywhere else. If they want to know what we’ve accomplished, they can read the ESM docs.
We do this as well; see the loaders section with its plentiful warnings. |
|
Please take notice that there is a link in the following sentence of the introduction of the ECMAScript Modules docs page, which currently expects
This PR, if merged, would move it to the archives causing that URL to turn up with nothing. I recommend we keep a page at |
README.md
Outdated
|
|
||
| ## Current Efforts | ||
|
|
||
| > ### [Current Plan for ECMAScript Modules support in Node.js](./doc/plan-for-new-modules-implementation.md) | ||
| ### To Do / In Progress |
There was a problem hiding this comment.
To be very blunt then, since you have asked me to be, I simply do not think this content is suitable for our readme. Since it is rapidly changing, likely to get out of date, and not the right information for someone "interested in the Node.js modules group".
As said before, I think we should separate this out into roadmap.md and previous-work.md.
There was a problem hiding this comment.
Latest commit in my PR to this branch may be what you're after.
There was a problem hiding this comment.
As said before, I think we should separate this out into roadmap.md and previous-work.md.
Would it be better to have something like a project board for the roadmap? So it can properly link to issues/PRs, including automatic status updates as things get closed?
There was a problem hiding this comment.
@jkrems, the argument against that approach, which was brought up to me when I proposed the exact same idea to @GeoffreyBooth, is that these things need to be archivable and a more-static public record of them needs to be kept.
Add notice of doc being archived & remove current efforts
|
@guybedford please review. This version just archives the features and old road map, without adding any new content. This will satisfy #473 while we figure out the best place to put that other content (like why named exports from CommonJS probably aren't coming soon). |
Resolves #473. This archives out-of-date content and puts on our README the most important information that most visitors to this repo are likely looking for.