Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Announcement blog post #291

Open
wants to merge 8 commits into
base: master
from

Conversation

@GeoffreyBooth
Copy link
Contributor

GeoffreyBooth commented Mar 13, 2019

Here’s a draft of what our announcement blog post could be.

https://github.com/nodejs/modules/blob/announcement/doc/announcement.md

Show resolved Hide resolved doc/announcement.md Outdated
@ljharb
Copy link
Contributor

ljharb left a comment

I object super strongly to the tone of this being "we've fixed the mjs thing you were all complaining about".

mjs remains the default, and the majority of the complaintants either lacked understanding of the nuances or wanted to discard critical use cases. I do not think it is at all appropriate to paint this as "you yelled at us, we were wrong, and we fixed it! (even though we didn't actually change any of the things you yelled about"

(I stopped reviewing halfway through because the overall messaging is very dismissive of the real and valid reasons mjs is explicitly necessary and has always been)

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated

## `import` and `export` syntax in `.js` files

Yes, we heard [you](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md). And [you](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054). And [you](https://twitter.com/maybekatz/status/1062473765865512961). You can now use `import` and `export` syntax in `.js` files.

This comment has been minimized.

@ljharb

ljharb Mar 13, 2019

Contributor

This seems a bit disingenuous, since that wasn't prevented before - it just was not, and still is not, the default.

This comment has been minimized.

@ljharb

ljharb Mar 15, 2019

Contributor

How is this something you can "now" do? This was something that was always planned; whether it happened to be shipped prior to the WG forming or not.

I do not want any implication that having an ESM .js file is suddenly an option because of this working group; we have merely preserved (and perhaps implemented) that option.

This comment has been minimized.

@GeoffreyBooth

GeoffreyBooth Mar 15, 2019

Author Contributor

The article is describing the new implementation as compared to the previous implementation. It’s not describing the new implementation’s plan as compared to the possibly not fully implemented plan for the previous implementation. I don’t think most people will know (or care) what the previous plan was, just what’s new in this version of the software versus the previous version.

This comment has been minimized.

@ljharb

ljharb Mar 15, 2019

Contributor

Given the "we heard you" rhetoric at the beginning of the paragraph, this is absolutely implying that it wasn't part of the plan from day one, which it was. If you're talking about implementation differences and capabilities, then talking about "responding to feedback", especially flippantly implying that those of us involved prior to the WG a) weren't listening, or b) weren't planning on enabling this anyways, doesn't belong here.

This comment has been minimized.

@GeoffreyBooth

GeoffreyBooth Mar 16, 2019

Author Contributor

this is absolutely implying that it wasn’t part of the plan from day one, which it was.

If supporting ESM in .js was ever the plan, shipping without any support for it certainly sent a message to the community that that wasn’t the final plan. I was an interested observer when the first --experimental-modules came out, probably a lot more interested than most, and I had no idea that ESM in .js was ever on Node’s roadmap.

Regardless, plans are never mentioned here. This text is just saying that we hear the request from the community loud and clear, and we’re responding to it. That’s not an indictment of anyone involved in the process so far. If anything, it shows that we’re good developers who are working hard to build the best product for our users.

This comment has been minimized.

@ljharb

ljharb Mar 16, 2019

Contributor

I'm still not OK with the wording in this paragraph. I'm not sure how to explain it any clearer, but please stop marking it as resolved; it is not.

This comment has been minimized.

@weswigham

weswigham Mar 16, 2019

In terms of tone, I think it has much the same issue as the "we didn't do this to annoy you" line did. In isolation it might seem conciliatory, but mentioning it at all is only likely to incense anyone who feels these results are only a half-measure. It doesn't sound good to many of the people it's meant to ease the minds of.

This comment has been minimized.

@robpalme

robpalme Mar 16, 2019

Contributor

All we need is a simple statement that modules can use the JS extension.

That will be enough. It's super clear.

We should avoid referencing individuals that have taken particular positions in the past, because that frames it as a conflict between different sides, whereas it's more of a collaboration.

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
@weswigham
Copy link

weswigham left a comment

In addition, I think @ljharb's comments on the tone of the .mjs bit are pretty valid.

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
@SMotaal

This comment has been minimized.

Copy link
Contributor

SMotaal commented Mar 13, 2019

@GeoffreyBooth reading over the rendered document, I have a more general consideration.

People will likely lose track of which --experimental-modules you will be referring to, not all share in the knowledge of more than one.

Does it make sense to always be explicit when first talking about either one in a separate context? ie always use the exact same way to refer to previous or new implementation since they are all flagged at this point.

Suggestions: (use emojis)

new --experimental-modules old --experimental-modules ❤️
--experimental-modules v1 --experimental-modules v2 👍
--experimental-modules alpha --experimental-modules beta 🚀
@robpalme
Copy link
Contributor

robpalme left a comment

Thank you for writing this up!

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
@GeoffreyBooth

This comment has been minimized.

Copy link
Contributor Author

GeoffreyBooth commented Mar 13, 2019

Let’s just settle this. The docs sub-group discussed and decided on the spelling “ES module” to match “CommonJS module”. If you agree with this, click 👍 below. If you prefer “ES Module” click 👎 below.

Edit: The 👍s have it, as of this writing, so I’m going to mark as resolved all the “change spelling” requests. If the numbers flip, among members of the group, I’ll make the change.

@devsnek

This comment has been minimized.

Copy link
Member

devsnek commented Mar 13, 2019

@GeoffreyBooth is that referring to a source text module or some abstract module (which could be a stm)

@GeoffreyBooth

This comment has been minimized.

Copy link
Contributor Author

GeoffreyBooth commented Mar 14, 2019

@GeoffreyBooth is that referring to a source text module or some abstract module (which could be a stm)

Why do you ask, so you can point me to some spec text where everything is capitalized? This is a blog post, not spec text. An ES module is whatever the average user thinks it is, which I would think is probably a file or string containing import or export syntax, or a file or string intended to be loaded as if it had such syntax (i.e. an ambiguous file within an otherwise ES module project). “Loaded as an ES module” means that Node would evaluate the file expecting that it has or might have import/export syntax.

@devsnek

This comment has been minimized.

Copy link
Member

devsnek commented Mar 14, 2019

@GeoffreyBooth because if its some abstract module i'd say "es module" (i don't care about the capitalization there) and if its a source text module i'd say "source text module" (we already refer to it as such in the vm api)

@MylesBorins MylesBorins referenced this pull request Mar 14, 2019

Closed

New ESM Implementation #60

@GeoffreyBooth GeoffreyBooth force-pushed the announcement branch from cf24a46 to 6dee5cd Mar 14, 2019

@GeoffreyBooth

This comment has been minimized.

Copy link
Contributor Author

GeoffreyBooth commented Mar 14, 2019

I think I’ve addressed all the feedback, at least that was clear on how I should address it. I’m not sure what changes to make regarding the dual packages/"module" paragraph, and @weswigham I made some changes to the extensions searching paragraph but I’m not sure all your concerns are addressed. Regarding that feature I think we need to explain our motivations (that was part of the discussion on flagging it) but I agree it should be presented as neutrally as possible, so if you want to suggest alternate language there we can continue to iterate.

@GeoffreyBooth GeoffreyBooth requested review from weswigham , robpalme and ljharb Mar 15, 2019

Show resolved Hide resolved doc/announcement.md

## `import` and `export` syntax in `.js` files

Yes, we heard [you](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md). And [you](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054). And [you](https://twitter.com/maybekatz/status/1062473765865512961). You can now use `import` and `export` syntax in `.js` files.

This comment has been minimized.

@ljharb

ljharb Mar 15, 2019

Contributor

How is this something you can "now" do? This was something that was always planned; whether it happened to be shipped prior to the WG forming or not.

I do not want any implication that having an ESM .js file is suddenly an option because of this working group; we have merely preserved (and perhaps implemented) that option.

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md Outdated
@GeoffreyBooth

This comment has been minimized.

Copy link
Contributor Author

GeoffreyBooth commented Mar 16, 2019

Okay, I’ve addressed all of the feedback posted above, either through the revisions in the document or through replies in the comments. Some of the comment threads didn’t have clear direction for me to know what to do about, as I’ve written above; if people can come to a consensus on what we want to do regarding those parts of the document, I’m happy to make those changes.

@MylesBorins plans to open the PR for upstreaming on Monday 2019-03-18, and I think this should be merged in before then so that his PR can link to this document at its final URL in the repo. We can continue to revise it before it’s published to the world as our announcement blog post. I understand some folks still disagree with some of the things I’ve written here; I would ask that we merge this in and you can propose alternate text in PRs against this document, and those PRs can be debated, possibly in a meeting.

@ljharb

This comment has been minimized.

Copy link
Contributor

ljharb commented Mar 16, 2019

I'd prefer no announcement whatsoever over an announcement that conveys a flippant tone about .mjs and "ESM in .js files"; I think it's better to leave this unmerged than to merge it before we're all on board with it.

Show resolved Hide resolved doc/announcement.md Outdated
@GeoffreyBooth

This comment has been minimized.

Copy link
Contributor Author

GeoffreyBooth commented Mar 16, 2019

I’d prefer no announcement whatsoever over an announcement that conveys a flippant tone about .mjs and “ESM in .js files”

I removed the entire paragraph that was criticized for its tone. I don’t feel that the remaining very brief mention of import and export syntax in .js is flippant at all. Flippant is “not showing a serious or respectful attitude.” I don’t think there’s anything flippant about saying that we heard user feedback and addressed it; if anything, that is respectful, of our community. I think telling users that we’re listening to them and responding to their feedback is critical to encouraging trust and adoption and making this entire effort a success. I think that’s the most important part of this document.

@weswigham weswigham self-requested a review Mar 16, 2019

@guybedford
Copy link
Contributor

guybedford left a comment

Just a few comments. Let me know if I can clarify further at all.

Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md Outdated
Show resolved Hide resolved doc/announcement.md

@GeoffreyBooth GeoffreyBooth force-pushed the announcement branch from 33c2a37 to 1116d7d Mar 16, 2019

@GeoffreyBooth GeoffreyBooth force-pushed the announcement branch from 57599f4 to 4be23c8 Mar 17, 2019

@GeoffreyBooth GeoffreyBooth requested a review from ljharb Mar 18, 2019

@MylesBorins MylesBorins added this to Work in progress in Upstream to core Mar 19, 2019

@MylesBorins MylesBorins added this to the Upstream milestone Mar 19, 2019


## `import` and `export` syntax in `.js` files

We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.

This comment has been minimized.

@ljharb

ljharb Mar 21, 2019

Contributor

Thanks, this is much better - I'd still prefer to indicate that this was always part of the plan (just was never planned to be the default, as it still is not).

This comment has been minimized.

@GeoffreyBooth

GeoffreyBooth Mar 21, 2019

Author Contributor

This language was the result of a lot of back and forth between various people, so I'd rather not open it up again for debate if you don't mind? Could this be acceptable to you?

This comment has been minimized.

@ljharb

ljharb Mar 21, 2019

Contributor

I'm not sure why "how many people that weren't me" you talked to should mean that I don't get to retain my opinion here.

This comment has been minimized.

@GeoffreyBooth

GeoffreyBooth Mar 22, 2019

Author Contributor

Looking at the previous implementation’s user-facing docs and design doc, the previous plan for supporting ESM in .js files was via a loader as shown in the example here.

How about we change “Node.js needs to provide a way to use import and export syntax in .js files” to “Node.js needs to provide a way to use import and export syntax in .js files without requiring a loader.” Would that be acceptable?

cc @weswigham @robpalme

This comment has been minimized.

@bmeck

bmeck Mar 22, 2019

Member

Guy and myself had plenty of talks about different ways to declare formats prior to the wg forming, if you need me to dig up gists etc. I can, but the talks did occur both in EP and after the initial implementation. I am rather busy but is it really necessary to bicker about the timelines so much?

This comment has been minimized.

@robpalme

robpalme Mar 22, 2019

Contributor

My original point was that the history doesn't matter.

Whilst I'm happy with the wording as-is, if you wish to discard the historical/controversy angle, that's fine too. The content already sells itself, so the more boring/factual the better IMO.

This comment has been minimized.

@ljharb

ljharb Mar 23, 2019

Contributor

per offline discussion:

Suggested change
We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.
We heard feedback that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.

This comment has been minimized.

@SMotaal

SMotaal Mar 24, 2019

Contributor
Outdated — for context only

It may be worthwhile to note that feedback is different from what was heard, imho wording this needs to balance from both sides and be slightly biased towards the reader (ie they will be doing the effort to read and use this after all).

We are make a lot of progress towards popular features demanded by members of the community and in ways that will ensure that all existing projects can continue to operate smoothly.

With this new implementation, we are making it possible for the first time to actually import and export from .js files with opt-in package configuration or CLI flags directly, ie no longer requiring a custom loader.

This suggestion focuses on the substance, but I sincerely think that references from which we claim to infer such demand are necessary somewhere in the announcement — it is appropriate blogging decorum and ensures tracking with a proper chronological structure.

So we need a way to relate to those links:

I suggest considering a second statement in the first paragraph making the case from those links that is addressed in the next paragraph. This would flow well for the reader and be very balanced to both Node.js and the community.

I worry that being too sensitive here comes off negatively for Node.js — did we not just give a solution that was asked for here after insisting we will never ever do that?! If we tiptoe about that, the reader will be inclined to think it, but if we assert the correct narrative, it keeps readers focused on the exciting new features, and frames those links as one community working towards one goal.

This comment has been minimized.

@SMotaal

SMotaal Mar 24, 2019

Contributor

That suggestion which I strongly recommend based on the cases made in my previous outdated one would look more like this:

Suggested change
We heard some [very](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) [strong](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054) [feedback](https://twitter.com/maybekatz/status/1062473765865512961) that Node.js needs to provide a way to use `import` and `export` syntax in `.js` files.
We are make a lot of progress towards some [popular features demanded by members of the community](https://twitter.com/maybekatz/status/1062473765865512961) and in ways that will ensure that all existing projects can continue to operate smoothly. This required a lot of careful consideration and insights from community discussions on how [the community uses ESM in projects today](https://github.com/dherman/defense-of-dot-js/blob/master/proposal.md) and [possible ways for packages to move forward](https://gist.github.com/ceejbot/b49f8789b2ab6b09548ccb72813a1054).
With this new implementation, we are making it possible for the first time to actually `import` and `export` from `.js` files with opt-in package configuration or CLI flags directly, ie no longer requiring a custom loader.
Preview

We are make a lot of progress towards some popular features demanded by members of the community and in ways that will ensure that all existing projects can continue to operate smoothly. This required a lot of careful consideration and insights from community discussions on how the community uses ESM in projects today and possible ways for packages to move forward.

With this new implementation, we are making it possible for the first time to actually import and export from .js files with opt-in package configuration or CLI flags directly, ie no longer requiring a custom loader.

This comment has been minimized.

@ljharb

ljharb Mar 24, 2019

Contributor

No, because nobody insisted we would never do that. With or without any of this feedback, we would always have provided some way to have ESM in .js - predating the WG as well. Thus, the links aren’t relevant, and would further the misconception that this is a newly intended feature.

@MylesBorins

This comment has been minimized.

Copy link
Member

MylesBorins commented Mar 24, 2019

@ljharb

This comment has been minimized.

Copy link
Contributor

ljharb commented Mar 24, 2019

I think so - I think this language achieves that.

@ljharb

This comment has been minimized.

Copy link
Contributor

ljharb commented Mar 24, 2019

@GeoffreyBooth and I discussed things a bit offline; if by tomorrow night the two of us haven't been able to agree on better text, I'm going to go ahead and stamp with the current phrasing (also OK with this tweak, but not required).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.