doc: add compatibility/interop technical value

[GeoffreyBooth]

I think it’s important to note that Node.js is part of the JavaScript ecosystem, and that broader community is a big reason for Node’s popularity. Node should be a good citizen and avoid actions which fragment that ecosystem.

Re #35145 (comment)

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[mhdawson]

Tagged for the next-10 agenda.

[mhdawson]

Discussion from the next-10 meeting was that those in the meeting were more comfortable with:

Compatibility and interoperability with browsers and other JavaScript environments where it fits in the Node.js context

EDIT, still discussing at this point, posted too soon.

[mhdawson]

We ran out of time so, people from the team will jump in here directly to continue the discussion.

[GeoffreyBooth]

I’m not sure what “where it fits in the Node.js context” means. Couldn’t you say that about any of the values in this document?

I’m happy to discuss any concerns people have.

[ronag]

I didn't take part of the meeting discussing this but there is a relevant discussion going on here which might be contradicting this PR at might be worth taking into consideration.

[GeoffreyBooth]

I didn’t take part of the meeting discussing this but there is a relevant discussion going on here which might be contradicting this PR at might be worth taking into consideration.

So the idea behind this technical value is that Node should try to encourage more JavaScript that can run both in Node and in other JavaScript environments. The more we push people into Node-specific APIs, the less portable their JavaScript becomes; and that harms the ecosystem as a whole. Sure there are tools like Browserify that can take JavaScript written for Node and convert it to run in browsers, assuming no unpolyfillable Node APIs are used, but that’s a band-aid on the problem. And yes, there will be times when this means that Node uses an API or syntax that’s less powerful than something that Node could come up with on its own, but that’s the cost of compatibility. I understand that many of the people closely involved with the Node project are the ones least likely to want to see it constrained by things like what browsers are capable of, but this technical value is here to remind us that what we lose by staying compatible is more than outweighed by what we gain by maintaining a vibrant JavaScript ecosystem. Arguably it’s that ecosystem that led to Node’s popularity in the first place, and what will keep Node popular in the future against other non-JavaScript alternatives.

[ronag]

So the idea behind this technical value is that Node should try to encourage more JavaScript that can run both in Node and in other JavaScript environments.

I'm a bit worried in regards to what the consensus on the importance this is relative to other factors? I think last time it was quite explicitly put as Priority 5 and in that meeting there were quite a lot of participants. Not saying we can't change it but I think we should have some form of consensus... Maybe there is...?

[ronag]

Tagged for the next-10 agenda.

Ah, missed this. Good. I think this can be an interesting topic to discuss.

[GeoffreyBooth]

I think last time it was quite explicitly put as Priority 5

I think there’s a difference between what’s currently in Priority 5 “Web API compatibility” and what I’m describing here. There are things that greatly impact ecosystem compatibility that aren’t Web APIs like JavaScript syntax itself, the module system, etc.

Also by putting it in the lowest priority, that means that anything above it by definition is a higher priority, such as performance. We shouldn’t break compatibility just because we think our way is faster. We can include our way as a new API, that doesn’t overlap with an API or syntax that browsers use, and we should. But just as browsers have a goal of “don’t break the Web,” Node should have a goal of “don’t break the ecosystem.”

[wesleytodd]

Node should have a goal of “don’t break the ecosystem.”

If we are going to have a value toward this on the list, I think this should be the wording. That said, the browser is much more widely deployed and thus has much higher stakes when a breakage is introduced. I think our stakes are lower, and so some breakage is good.

When it makes more sense to offer alternative apis which give better perf or developer exp (two things listed with higher priority) then I think we need to do so. Which is the point of the change @mhdawson proposed above. We don't want "compatibility at all costs" IMO.

[GeoffreyBooth]

When it makes more sense to offer alternative apis

If it’s an alternative API, then it’s not a risk to compatibility. Node can offer its own url builtin module, if it wants, but the global URL variable should behave the same way and have the same API as window.URL in browsers.

The goal is the JavaScript code that users write should behave the same way when run by Node as when run by browsers. Just as including an if statement to have separate code for separate browsers is bad, we should avoid anything that would cause users to need to write Node-specific code (other than users explicitly importing APIs that browsers lack, just as there are Web APIs that Node lacks). Where there is overlap, Node should maximize compatibility.

I think our stakes are lower, and so some breakage is good.

I think the bar for breaking compatibility should be very high, higher than anything in Priority 2 or below. Especially since most things can be implemented in ways that don’t break compatibility, like offering alternative APIs. Another technical value we could add to this list is that “Node.js is spec-compliant”—it’s so obvious that apparently it goes without saying, but it does come up (and came up a lot for me in the modules team, as we struggled to implement import/export in a developer-friendly way without breaking spec). Especially now that we do have a module system that is shared with browsers, the future should hold more and more code that is intended to run in both client and server environments, so we should ensure that as much of such code as possible runs correctly in both. Our stakes are growing higher.

[mhdawson]

From my perspective it's finding the right balance in the wording.

I think our project values compatibility and there is agreement that it is part of what made Node.js successful in the first 10 years but there are differing views with respect to how it is balanced against other priorities. My take is that (likely biased by my view) is that the shared value is closer to compatibility when it makes sense versus compatibility at all costs. In the first case compatibility is the goal unless there is a good reason why that's not the best choice which is quite possible because Node.js is not a browser.

[mhdawson]

And when I say shared value that's looking for the overlap that is acceptable across the collaborator base, versus making everybody happy or that everybody has the same view.

[Qard]

I think there's also a case for pointing out the value for supporting/integrating with browser tech without necessarily using it. For example, my note in the call about the possibility of making Node.js streams and ES streams convertible from one to the other. I don't think it makes sense to rip out all the existing streams stuff we have and switch it all to es streams, but I think it does make sense to augment the API in ways that make them cross-compatible with standards equivalents. We already do this with consuming a stream as an async iterable, and I think we should continue to pursue ways to make optional ways to use APIs such that they will function in harmony with the standards-based equivalents.

[wesleytodd]

Notes for today's meeting in nodejs/next-10:

• @GeoffreyBooth It would be awesome if you could come to the next one so we can nail down a better way to approach this topic
• One proposed idea is to break out a whole new section to illustrate how there is a venn diagram like overlap between node and web apis. The new section would talk about how this topic spans many priorities and depends alot on which specific api is being discussed.

[GeoffreyBooth]

• It would be awesome if you could come to the next one so we can nail down a better way to approach this topic

I would be happy to attend, if you could add me to the invite.

I think it’s more than just APIs. It’s maximizing the amount of code that can run without modification in both browsers and Node. The more different that Node is, and the more that code needs to be written specifically for Node, the less benefit there is from Node being a JavaScript runtime. Viewed another way, if you have to write server-specific code, why use Node or JavaScript at all as opposed to any other language? Sure, there’s benefit from not needing to context-switch or hire developers who know multiple languages, but there’s more benefit the more we can minimize the differences and maximize code sharing/reuse. That’s a big part of the sales pitch of Deno, for example, and they have a point. We don’t need to go as far as they do, but we should prefer compatibility and interoperability wherever possible.

[GeoffreyBooth]

Worth adding to the discussion: https://www.youtube.com/watch?v=o2M7g8Xwc7g / https://kni.sh/the-future-of-javascript-is-universal/ by @MylesBorins

[mhdawson]

@GeoffreyBooth there is no invite. It's in the Node.js calendar: nodejs.org/calendar and and issue is created in the repo a few days in advance. Could you add your own calendar entry as a reminder?

[mhdawson]

LGTM

[mhdawson]

As a note we discussed in the Next-10 meeting today and PR has been updated to reflect that discussion.

[GeoffreyBooth]

Just want to add this here since I thought it was a good point that @MylesBorins made as we discussed this: arguably another value we could add is something like “Users should only need to learn JavaScript, not Node.js.” As in, no one should have to first learn JavaScript and then take another class/tutorial/read a book on Node.js—the skills should be transferable, and/or Node should behave so similarly to other JavaScript environments that it shouldn’t require its own dedicated learning curve.

Kind of like how you learn to write frontend code, not frontend code for Chrome and then frontend code for Firefox (unlike 10-20 years ago, thankfully, where writing browser/IE-specific code really was a thing, especially before jQuery). I think currently Node is closer to the “learn how to do it in Chrome, then learn how to do it in IE” developer experience of frontend in 2015 or 2010, but I would hope that we’re following the trajectory of browsers and closing the gap as time goes on. ES modules were a big step in that direction, and I hope other improvements to Node get us closer still.

[mmarchini]

I think currently Node is closer to the “learn how to do it in Chrome, then learn how to do it in IE” developer experience of frontend in 2015 or 2010

I disagree with that statement in the sense that was brought up in the meeting. Node.js implements the JavaScript spec and users don't have to learn a different flavor of JavaScript to use it. fetch and other examples are WHATWG/Web/HTML spec and does not fit the "Users should only need to learn JavaScript, not Node.js" statement. JavaScript compatibility and other specs compatibility are different topics.

[mhdawson]

I think this is ready to land, will land in the next day or so unless there are new comments.

[mhdawson]

Landed in 700612f