Define shipping criteria

[MylesBorins]

What should be the criteria for shipping Modules in Node without a flag?

I'll keep this original comment up to date with the current state of the discussion in this issue

[devsnek]

off the top of my head:

• figuring out how builtins will be exposed to esm (discussion ongoing)
• if/how vm.Module integrates into the node module loader
• per-package hooks
• whatever is happening with cjs interop and that npm proposal

[targos]

What is that npm proposal?

[devsnek]

https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054

[jasnell]

three key things for me:

1. We must have a strategy for exposing the full Node.js core API via ESM with named imports figured out.
2. We must have a strategy for exposing deprecating non-function exports via ESM (this could mean simply not exposing non-function exports via ESM... examples... fs.promises, path.win32, crypto.DEFAULT_ENCODING and crypto.fips
3. We must have the assume-ESM-by-default strategy worked out (e.g. using either the package.json flag, a command line flag, etc)

[giltayar]

One thing for me, which is more of a soft consideration:

• Provide an explanation of how to migrate existing apps and npm packages to ESM in a way that is incremental.

This explanation (as a blog post? readme? officially in the node documentation would be best) would help the community understand how to get from 0% esm in the world to 99% esm in the world, and how this affects them.

This explanation will enable us to understand the migration implications of the final proposal.

Without this understanding, we may find ourselves in a python3 situation.

[mcollina]

Two cents from me:

• Provide a proof-of-concept (with tests, maybe in core) for an APM implementation. This includes having documented loaders, and maybe specifying those loaders from JS, too.
• Documenting (and maybe have an ecosystem module) on how to do stubbing and mocking in the ESM world, e.g. something like "proxyquire" for cjs. If this is not possible, it should be noted in the docs.

[targos]

Not really a shipping criterion, but I think it's important that we unflag Modules in Node 10, before it reaches LTS. That means two things:

• If semver-major changes to stable APIs are necessary, we must do them before April 2018.
• Other changes to Modules that would be considered semver-major if the feature was stable must be done before October 2018.

[bmeck]

@mcollina

Provide a proof-of-concept (with tests, maybe in core) for an APM implementation.

Would putting https://github.com/bmeck/node-apm-loader-example in the docs and doing some cleanup be enough? What are the reasons to put it into core? Just for testing purposes / could it be in CITGM?

This includes having documented loaders, and maybe specifying those loaders from JS, too.

I'd push out the loaders from JS as far as possible since static loaders can already expose themselves to existing JS and do crazy dynamic injection.

---

For my criteria it is probably more minimal than most:

1. We must be able to ensure that a module written does not load in the opposing system accidentally / cannot produce cache inconsistency (think case insensitive file system problems [but for module systems]).

2. We must provide workflows for existing use cases when moving from CJS to ESM even if they require breaking changes to existing code. In particular:

• APM
• Mocking
• Transpilation

3. We must ensure that we do not ship any feature that is deemed to be incompatible with web workflows. This is not to say that everything must run on the web without tooling / changes to dependencies. This is purely about preventing any sort of planned [permanent] tech debt being shipped before we start a mass migration to ESM. This has an implied requirement of being able to run things ahead of time and is why I will push against shipping any mutable JS hooks for ESM.

[mcollina]

Would putting https://github.com/bmeck/node-apm-loader-example in the docs and doing some cleanup be enough?

Yes, I think so.

What are the reasons to put it into core? Just for testing purposes / could it be in CITGM?

My reasons is avoid breaking things unintentionally for this specific use case. I think that has no unit tests at the moment, so that would have to be fixed.
Having some form of crude (1 or 2) unit tests in core would help in not breaking that behavior (CITGM is not run every time). Adding it to CITGM would work the same.

[ceejbot]

I am going to give an answer that's 100% software engineering basics.

• We should have a clear statement of goals, with explicit non-goals called out if that helps.
• We should have an agreed-upon set of use cases to enable.
• We should have a technical design that enables those use cases (whatever they are), with an API we're willing to support over the long term.
• We should have an implementation of that design, with tests to demonstrate success of the use cases.
• We should have documentation & examples.

I see assumptions of some goals & design choices above. If those are already selected, we should document them in this repo. A concise plain-language design document for our goals will help with both getting us all to share the same vision and with communicating that vision outward.

[MylesBorins]

Closing for now, we can revisit this as we expand on minimal kernel