Lets document the current state of Modules in Node.js

[MylesBorins]

Folks from the TSC need to ramp up on the current state of our implementation, decisions we've made, in progress features, and areas we lack consensus. While we do have https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md I don't think it is the best place for someone to get a holistic view of where we are at.

Made a google doc to collect our ideas.

https://docs.google.com/document/d/1rgXyCQP6S694MzkXla8rbRwqCSY9Eb2lFIOgLZoEw5k/edit?usp=sharing

FWIW we could turn this into another blog when we unflag... might not be a bad idea.

[MylesBorins]

/cc @nodejs/tsc

[ljharb]

Ideally this will mostly be a completely neutral article, but where there are points of disagreement, it'd be great to have a kind of "editorial paragraph" for each side explaining the positions.

[MylesBorins]

@ljharb are you ok with keeping disagreements / editorialization scoped to the issue of dual-mode packages and the specifier hazard? I'd like too avoid re litigating other parts of the implementation

[ljharb]

I would also hope to minimize the points of public disagreement - we don't want to have this document appear incohesive - but I think it's too early to commit to that until the document is more fleshed out.

[GeoffreyBooth]

I would also hope to minimize the points of public disagreement - we don’t want to have this document appear incohesive - but I think it’s too early to commit to that until the document is more fleshed out.

@ljharb you’re the one who requested TSC review. What would you potentially want them to review beyond the hazard / dual package divergent specifiers?

[ljharb]

To properly ramp up, they'd need maximum context - including trying to understand where all our perspectives come from. This involves more than just the decisions at hand.

[GeoffreyBooth]

What would you potentially want them to review beyond the hazard / dual package divergent specifiers?

[ljharb]

Not sure yet; I'll let you know as the document fleshes out :-)

[GeoffreyBooth]

The state of modules is https://nodejs.org/api/esm.html. The document would basically just be that, plus whatever points of disagreement we have.

So if you don’t have any others, we can point them to those docs and write a section about the hazard / dual package divergent specifiers, and that’s it.

I don’t think the TSC wants to be pulled in to referee any disagreements we may have. They already kicked the @/~ decision back to us. We should only involve them for major issues that might affect the public perception of Node.

[ljharb]

I'm not suggesting they'd change already-decided things - but it's still important for them to know the context.

[MylesBorins]

Shared with the TSC. We can revisit later if we want to turn this into some sort of blog post.