Roadmap

[mikeal]

The culmination of a lot of work in various issues and PRs.

Let the bikeshedding begin.

PS. @chrisdickinson will surely comment that we really need to find a place to put these documents that isn't just in the root of the project and I agree but until we have such a place I'll continue to post them like this :P

[ruimarinho]

Typo on maintinence.

[ruimarinho]

Nice work! It feels really good to finally have the long term plans organized like this 👏

[mikeal]

Just landed a ton of edits based on this early feedback.

[domenic]

Here you starting switching to code-ifying io.js instead of io.js.

[chrisdickinson]

This comment got blown away by an unrelated change. Reposting it because I'd like it to be more generally visible, sorry for the double post:

The NG proposal seems overreaching to me:

What do we need to experiment with regarding ES2015 primitives that would require putting a ES2015-module-syntax wall around them? There's a happy path for promises and the callback api to co-exist, so promise support shouldn't need to be walled as it can be purely additive. Streams are so invasive that changing that base primitive means we need to rewrite all of the stream-exposing APIs in node, which leads to use having two separate systems to maintain, a result I'm not fond of.

Why prompts the need to state a NG? Could we say something like "we will experiment with adding support ES2015 features behind feature flags, unflagging them as we're confident they are production-ready," followed by a list of the ES2015/WHATWG features we're actively looking at supporting (promises, whatwg/stream compat, etc)? Using the new module syntax as a gating method seems like an attractive idea, but I'm not sure we need to use it in order to build a better platform.

[mikeal]

Notice that I removed reference to NG as having builds.

NG is here to do a couple things:

1. Commit to doing a next generation version of the platform more in line with where JavaScript is in a year or so than where it was 6 years ago.
2. Identify the mechanism (native ES6 modules) by which we can release this platform in the future without breaking any of the existing ecosytem.
3. Give people a contribution endpoint where they can work on it.
   • This means work on future tech won't block continued stable releases.
   • This means continued stable releases won't block work on future tech.

The rest of your comments are all things that should be up for debate and iteration and if there are any places where it seems like we're committing to doing one thing or another let me know so that we can remove them ;)

[chrisdickinson]

Identify the mechanism (native ES6 modules) by which we can release this platform in the future without breaking any of the existing ecosytem.

Do we need to identify the mechanism in this roadmap? I'm not sold on the idea of using ES0xF module syntax to gate new functionality this way:

• It's unclear when we start encouraging folks to make use of these features (shades of python3).
• I'm not sure how much code would reasonably be shared between io.js OG and NG, so it feels like a second system.
• I'm not sure that for the most interesting ES0xF changes, like adopting promises / async+await / generators, that those APIs could not live alongside or otherwise get brundle-fly'ed into our existing APIs. AFAIK things like typedarrays still have specific requirements that don't meet our needs for performance reasons. Is NG about ES0xF features, or about revisiting JS APIs? If it's about the latter, I'm not sure that there are really compelling reasons to commit to this specific mechanism up-front.

My preference here is to avoid committing to a far-reaching mechanism like module-syntax-gating until it becomes clear that feature flags alone aren't sufficient to get us to where we want to be.

[mikeal]

Without a delivery mechanism we do little to alleviate peoples compatibility fears or convince people working on NG that their code will ship.

However, this roadmap is a living document and is editable. Are we fine with saying the current plan for delivery is by use of new module syntax but if we have a better idea of course we're going to change it?

[chrisdickinson]

If possible I'd like to go the --es-staging route and introduce an --iojs-staging flag (and corresponding IOJS_STAGING=1 env flag, for folks who use shebangs), that we can start landing promisifying PRs behind that – assuming that in either case we need to build this support out in io.js before we start accepting PRs / having people work on NG.

[chrisdickinson]

Admittedly a flag functions a lot less well as a metaphorical place for folks to do work / combine efforts than a separate set of modules; I understand the desire to have a location for folks to do the work of iterating on the API, but maybe that looks like an ng-wg issue/discussion repo instead of files within the repo?

[chrisdickinson]

I'm a little confused here. Are you saying that these flags will change the default platform or simply enable a new additive platform (available when using new module syntax)? I don't see how the current proposal excludes this.

The flags enable "next generation" features in the existing platform – for instance, returning promises from async APIs that are called sans callbacks, exposing the new module syntax, or experimental changes to streams.

[mikeal]

@chrisdickinson right, this will probably begin with just a WG repo and some issue threads. It could be that the platform can be built using a compile-to toolchain and doesn't even need to live in core until it is much farther along, that's why I don't want to get stuck on it being a build or a branch yet.

Once we have some tacit agreement about the roadmap I'll create the repo and kick off a few issues.

[chrisdickinson]

The feature flags don't imply the existence or necessity of a new set of modules at the outset. We can reserve module-syntax-gating for the future if we determine that it's absolutely necessary, but this lets us iterate until we get to that point. We may find that we don't need to start exposing a new platform.

[mikeal]

The flags enable "next generation" features in the existing platform – for instance, returning promises from async APIs that are called sans callbacks, exposing the new module syntax, or experimental changes to streams.

Extending the current API should be considered for regular releases and not block on theoretical future tech. I agree with the statement you've just made, I just don't see it as being under the same umbrella.

But, the reason I doubt we'll see something like that land is because it's such a drastic change for a fairly small gain in terms of the overall platform being friendly to new patterns. Doesn't mean we shouldn't try it out behind a flag though, especially since it's a good way to flush out issues we know we have with native promises (like we can't do AsyncWrap yet).

[chrisdickinson]

We might say "explore compatibility with WHATWG Streams", we may never implement WHATWG streams exactly. May also be worth linking "WHATWG Streams" to the github repo.

[mikeal]

Well, someone should implement a reverse compatible version of WHATWG streams but that shouldn't necessarily be readable-stream. I'll modify to the language here.

[chrisdickinson]

It might be worthwhile to include a one to two sentence definition of what a channel is in this context.

[ghost]

I disagree with what @sam-github said in issue #725 because that would mean breaking applications so what I would propose is give APIs that are broken/mistaken a special prefix so you can make a better version while still maintaining applications that require the old feature.

[mikeal]

@chrisdickinson I made some adjustments and deletions based on your feedback.

[mikeal]

I think all the feedback has been addressed. I think is ready to merge unless there are any objections?

[chrisdickinson]

This LGTM. Nice work!

[sam-github]

@BenjaminProgram re: #886 (comment)

Giving APIs we wish never existed a special prefix has a number of issues, beyond the awful cosmetics:

• it still breaks any existing app that uses the feature, they have to change the code, so why not just use the new better API?
• it doesn't work for behavioural changes (like client dgram sockets not being cluster distributed, or changing how cluster's worker.kill() works)
• it doesn't work when the goal is to remote the mistaken feature, like the domains code that was shotgunned into node, making node as a whole more complex

[ghost]

@sam-github Because sometime the app is not compatible with the better API, and it is easier to change the API name in code than to rewrite the code. But, I do see your points.

[piscisaureus]

Thanks Mikeal! Landed in 14174a9.