Modules: Initiative: Terminology / Historical Decisions documents

[SMotaal]

Motivation: In the last few days, while playing catch up to the things I missed in the last 3 weeks, I caught a glimpse of how challenging it would be for our future selves or others going through this repository's issues and documents when trying to pull together various threads.

Initiative: I'd like to propose and take part in an effort to put together terminology / historical decision documents which will allow us to keep track of easy-to-misread terms and how or why certain technical terms will evolve.

Volunteers: @smotaal @devsnek @bmeck @guybedford

Tasks:

• [X] Pick Format: GD
• [X] Determine Initial Structure: taxonomy-like
• [X] [Initial Draft](https://docs.google.com/document/d/1khaKKB1id0A52moNA9gbXE9bvV8Sisyr-IhC4i9dQdQ/edit?usp=sharing) (@smotaal)
• [X] Create terminology branch (@smotaal)
• [X] Create Terminology.md #158

[benjamingr]

Good initiative!

This should cover static/dynamic resolution, how named exports work, live bindings, differences between ESM and CJS, the various proposals in the past (summarized), where to find what in the repo (links to the use cases for example).

Would you be willing to take charge of it?

[MylesBorins]

I’ve added it to today’s agenda with a 5 minute time box

On May 23, 2018, at 2:22 PM, Benjamin Gruenbaum [e-mail] wrote:

Good initiative!

This should cover static/dynamic resolution, how named exports work, live bindings, differences between ESM and CJS, the various proposals in the past (summarized), where to find what in the repo (links to the use cases for example).

Would you be willing to take charge of it?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/nodejs/modules/issues/119#issuecomment-391449116, or mute the thread https://github.com/notifications/unsubscribe-auth/AAecVw18HUjcvHcPx4MW8q04n9V9CslUks5t1ajqgaJpZM4UK85g.

[SMotaal]

@benjamingr I understand the pain more than anyone at this point not to mention that I have a love-hate relationship with terminology.

Count me in definitely

It would be a lot more effective to have one or two other volunteers to increase the odds of it making sense to humans.

[bmeck]

I vote that we use a doc unless there is good reason to have version control. Not the biggest fan of wikis on github.

[GeoffreyBooth]

I was about to nominate a wiki, because it allows Markdown. I find the use cases/features docs hard to read because the code is all mangled in Google Docs.

[bmeck]

@GeoffreyBooth idk, comments are nice and allow issues to be done without needing to spin up a full github thread about specific terms, also it allows a nicer sharing mechanism that github wikis. if formatting is a concern we might be in big trouble since this is a list of terminology and collection of links and not a book with full on examples I would think. If we want to do full examples of each term with code highlighting that might a bigger goal than what I thought this was and would probably need its own project.

[GeoffreyBooth]

Okay, let’s start with a Google Doc then and see how it goes. Or if there’s some Google Drive app that allows editing Markdown, but with all the other features of Docs (comments etc.) that would be ideal.

[SMotaal]

After extensive research of all the options out there for a collaborative markdown editor which either integrates directly with Google Docs and/or offers as close to an experience for the collaborative features often used by the team in Google Docs I think we have a winner:

HackMD — Check out the Features (Fixed: Link was mistyped.)

My personal rating for features:

• Markdown ★★★★★
• Collaboration ★★★★⭐︎
• Integration ★★★⭐︎⭐︎

Pain points:

• Some non-GFM based syntaxes (also a plus)
• No repository integration (uses internal revisions)
• Lacking good description of service offerings (targeting self-host I presume)

More about Enterprise Edition

HackMD on GitHub

[SMotaal]

@bmeck @GeoffreyBooth @devsnek

Please take a look at HackMD because it might be a much needed upgrade to Google Docs in general and not just for this issue. If you have the bandwidth (and bandwidth in general) and want to see how it handles, consider taking it for a spin across multiple incognito windows. It is at least worthy of consideration, and working on Terminology there can be a good prelim.

[devsnek]

@SMotaal seems ok i guess. it has some rendering oddities in the editor panel that make me want to scream but besides that it should work. i think the one danger is moving into a new medium that isn't github or google docs. i don't think we (node.js) really have a protocol for that but i could be wrong.

[GeoffreyBooth]

@SMotaal Thanks for doing this research. I don’t have a strong preference, I’ll go with whatever people think is best.

HackMD looks pretty cool, though it doesn’t seem to support comments. Is that a dealbreaker for us?

[SMotaal]

@GeoffreyBooth It seems to only support a special block quote notation to indicate [name=Your Name] and other formatting aspects like [color=…]

I guess I got confused on that aspect with some other tool which offered comments, but none of those offered a stable enough experience for rapid collaborative drafting purposes. That is not to say that I know how HackMD would handle in a real-time multi-user hacking session, but like all things if it moves in the right direction, it can get there.

I have concerns, and surely everyone else does, most of which can simply be overcome by avoiding non-standard syntax. At which point, collaborative authoring in md is a step forward from say Google Docs converted to md via User Script or user. So unless Google Docs buys into md, any integration option out there is flaky at best.

[SMotaal]

@devsnek no doubt, it struggles, it seems like a WordPress template demo with all the features switched on.

[MylesBorins]

I'm not convinced that we need to add complexity of another tool for this
doc. A glossary is fairly straightforward and we can simply author in
Google docs and convert imho

If others are excited to try the tool, and are those who are going to be
doing the work, by all means run with it.

Just my two cents

On Wed, May 30, 2018, 12:43 PM Saleh Abdel Motaal [e-mail]
wrote:

@devsnek https://github.com/devsnek no doubt, it struggles, it seems
like a WordPress template demo with all the features switched on.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/nodejs/modules/issues/119#issuecomment-393115674, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAecVyNTUCk_jALiAlZtWVuOikuIFhEUks5t3nffgaJpZM4UK85g
.

[SMotaal]

@MylesBorins I totally agree. It was important to get this figured out while I pulled together the initial set of terms so that we don't put in a lot of effort only to end up having to redo everything.

So if I am getting everyone's inclinations correctly, we stay 100% Google Docs.

So here is the gist of the workflow (we're big on those in printing):

1. (Optionally) Start with unformatted markdown (but …)
2. Use the appropriate Docs formatting limited to features that would GFM markdown
3. If needed, use a GD to MD add-on/script

[bmeck]

Sounds good to me.

[SMotaal]

I began putting together the initial draft.

In order to make this document as useful as possible, my suggestion is to let it grow organically. So as a starting point, I basically extracted the links to all relevant concepts, productions... etc from ECMA-262 into a taxonomy-like document, whereby it becomes possible to infer the meaning from structure or otherwise by following the link.

From there we can all begin to make suggestions on how to improve or even completely replace the structure.

Ultimately, since it is far fetched to imagine we can really include definitions for all things, I am of the opinion that inference from structure and links are a really nice way to avoid all the potential pitfalls of having to maintain copied matter from sources with permalinks.

[guybedford]

Great to see things moving here, sorry for a delayed response on this.

I'm not sure how these things fit into the current structure, but here is an attempt at listing some terms we should try to ensure are adequately covered:

• Module resolution
• Resolution algorithm
• Module instantiation
• Module Linking
• Export binding
• Default export
• Named exports
• Circular references
• Function hoisting, TDZ
• Module namespace
• Module record
• Module execution
• Loader hooks
• Dynamic instantiation
• Declarative instantiation
• Dynamic import
• Import meta
• Module format
• Synchronous / Asynchronous execution
• Transparent interop (one-way / two-way)
• Conditional loading
• "mjs"
• Unambiguous grammar

I can gladly copy some of these over to the right places in the skeleton if it helps. Otherwise please feel free to integrate any of the above as you see fit @SMotaal, and then hopefully with the skeleton in place we can start to crowdsource the actual descriptions :)

[SMotaal]

To avoid discrepancies, I added TBD and Additions sections in the prologue to keep track of undefined terms and those worthy of revision or review.

@guybedford I already your list and did a quick sort to make it easy to go through them (assuming order was merely organic).

[SMotaal]

Now that we have diverse enough matter, I think it is important for us to deep dive into structure specifics. Our next goal should be to have a well structured document (without worrying about the completeness of the actual definitions) to get feedback around next meeting.

Let's use comments on the actual document to recommend, discuss and finalize this.

@bmeck @devsnek @guybedford

[GeoffreyBooth]

I was imagining a document more like a glossary, like just take each of @guybedford’s terms and define them, and that’s it. A single document with the spec and TC39 history and so on feels overwhelming.

[SMotaal]

@GeoffreyBooth I completely agree.

So at this point we're working on a single doc, but I imagine we will end up with more than one document and one of those will be just the glossary. I felt like getting things out of the spec was an important first step to make sure there is no conflict in any introduced terminology.

I am sure that others like myself may also find a document with only the relevant excerpts from the spec a very useful resource to help them focus on the important portions.

So, I guess it is a good point to ask everyone to list quickly the most important document(s) they believe are necessary for this project.

I think:

• Glossary: just a regular sorted list of terms and their definitions
• Relevant Specifications: taxonomy/hierarchy of links
• Normative References: documents which must be adhere to

[SMotaal]

I think what I just realized is that all our inputs so far (from the details aspect) is exclusively ES modules. We have not detailed things that makeup CJS, grammar, records... etc. I realize that NodeJS's documentation is exceptional, but that is all from the API consumer P/V not implementation.

Do you think any one of us is willing to take this part on. I wonder if maybe someone that is fluent in CJS evolution and especially interop-related caveats would be best suited to highlight the most important concepts/terminology to include.

[SMotaal]

@bmeck @GeoffreyBooth @guybedford @devsnek

This seems to be stalling with the obviously shifting priorities. Being on the outside, I don't think I am as able to set the appropriate scope of would be the most ideal form of a "Glossary" document for the team (downgrading it may be it). I don't think I can be productive working towards something that does not really align with the actual expectations and needs of everyone else in the group.

I'd like to pass the torch of setting the scope of our effort to someone else and I am more than happy to do the work, but planning this requires more insight at this point.

[GeoffreyBooth]

Maybe a starting point could be a document that just defines the list of terms in https://github.com/nodejs/modules/issues/119#issuecomment-395202322?

[SMotaal]

Okay, I shared a new Terminology document.

Please copy over what you think needs to remain.

Let's try to use comments in both docs to reach decisions together.

[robpalme]

@SMotaal I've attempted to begin population by starting with the most controversial term (transparent interop). It is an attempt to resolve https://github.com/nodejs/modules/issues/138

[guybedford]

How about promoting this link into the RESOURCES.md file here, and treat it as a living document at this point? As we come to any resolutions on terms during discussions, it would be great to keep it updated.

Alternatively we could create it as a separate TERMINOLOGY.md now that we have a skeleton, and then require specific approval on the consensus around terminology.

[guybedford]

@SMotaal I wouldn't worry too much about trying to get this perfect, in fact I think the minimal document here is all we need to start. Would be great to see this in this repo so we can continue to track process on terminology discussions as we build consensus on this.

[demurgos]

- Transparent migration ([#105](https://github.com/nodejs/modules/issues/105))
+ Agnostic consumer imports ([#105](https://github.com/nodejs/modules/issues/105))

• devsnek: i don't think this new term really describes what the feature is but i can't think of anything better.
• guybedford: @devsnek perhaps you can bring this topic to the terminology PR? I think these are important discussions to get agreement on there.

I'd like to bring this discussion here because it's important to have a clear and agreed up term and definition for this concept.

I also commented on this change in another thread:

demurgos:
Do you consider this feature to only cover ESM imports getting the same result regardless of the module kind of the dependency. Or does it also cover require being able to get the same result regardless of the dependency module kind?

These are distinct use cases and the various proposals support them differently. I would like to have a way to differentiate them.

I used "Agnostic ESM consumer" and "Agnostic CJS consumer" but this is not right because what matters is the import mechanism, not the module kind of the consumer. (you could use dynamic import() in a CJS module, or require in an ESM file) "Agnostic consumer import" (or "ES import") and "Agnostic consumer require" may be less ambiguous.
I just want to know if you consider "import" to also cover require?

---

I consider the term "import" to be ambiguous because it depends on the context. I see two possible interpretations:

• ES import: A static import statement or dynamic import() as defined by the ES spec.
• CJS or ES import: Either an ES import or a require (represents the abstract concept of importing something regardless of the concrete import mechanism)

Usually it's easy to get the correct meaning based on the context or formatting, but this is less reliable than having a single term. Formatting is easily lost when copy/pasting, and context is not always there (such as in the list of features).

I'd like to have a term for talking about imports in general as opposed to ES imports specifically.

---

Now, regarding the "Transparent interop/Agnostic consumer [import]", the goal is to represent the concept that the consumer code does not depend on the module kind of the provider. It means that as long as the producer exposes the same API, the producer implementation can change between CJS and ESM without breaking the consumer (no visible change, semver patch update).

I'd also argue that it is important to specify the import mechanism of the consumer because this what actually matters when defining what a proposal enables or not.
Given that, I'd propose the following definitions:

• Agnostic consumer using ES imports: Consumer module (either CJS or ESM) that uses static import or dynamic import() to get a value from a producer of unknown module kind.
• Agnostic consumer using CJS require: Consumer module (either CJS or ESM) that uses require calls to get a value from a producer of unknown module kind.
• Agnostic consumer: Agnostic consumer using CJS require or ES imports

I share the feeling that "agnostic" may not be the best term. I'd be happy if someone has a better idea, but the most important is to have an agreed upon meaning. A better term would help people to understand the meaning without reading the definition. In this context "agnostic" means "Independent of the dependency module kind" (etymologically, it's "without knowledge").

---

I'd also like to share here my feeling around the form "consumer-agnostic import":

demurgos:
As it stands, "Consumer-agnostic import" may be interpreted with the reversed meaning "The dependency is imported by a consumer of unknown module kind" (which is a meaningful thing to ask, see #139).

---

PS: I use "module kind" to cover modules acting like CJS or like ESM, but it is larger than Javascript files. For example, using --experimental-modules, WASM acts like ESM, .json and .node acts like CJS.

[SMotaal]

Okay everyone... Seeing that there is enough energy for this to sail through, and especially since I just finished a three week pivot on one of my on long-term large-scale experimentals - this one involving (almost) full stack ESM - it's time to get this moving forward. Let me pull the threads throughout the day and follow through to conclude this today.

[SMotaal]

@guybedford I tried to not get this perfect, but I guess I am just that awesome 😜

Okay, I tried three different options because as it turns Github Flavoured Markdown (GFM) (and other mainstream flavours) do not have a commonly accepted syntax for definition list elements, including
<dl> Definition List, <dt> Definition Term, or <dd> Definition. This is nothing new except those are the major building features of this document so riddling it with html markup might get in the way.

Please have a look at the options (both rendered and source):

Markdown: https://github.com/SMotaal/meta/blob/master/Node.js/Terminology/Definitions.md

reStructuredText: https://github.com/SMotaal/meta/blob/master/Node.js/Terminology/Definitions.rst

AsciiDoc: https://github.com/SMotaal/meta/blob/master/Node.js/Terminology/Definitions.asciidoc

If anyone knowns how to markdown definition lists (in case I missed it) please let me know, because after trying to work with the alternatives (which all have cool things too) markdown+html wins in my books.

Thanks to everyone who has contributed in our slow process, I would really appreciate everyone's continued collaboration on this now that we almost have a document to work with in the repo.

[demurgos]

This term alone does not specify in which direction(s) the agnosticism applies.

What kind of "direction" do you have in mind? I really want to differentiate a consumer not knowing the module kind of its dependency from a dependency/provider not knowing the type of the importing module ("agnostic provider"?).

---

If anyone knowns how to markdown definition lists (in case I missed it) please let me know, because after trying to work with the alternatives (which all have cool things too) markdown+html wins in my books.

I'd use headings for the definition term. It creates anchors allowing to link directly to a definition.

[SMotaal]

@demurgos sorry for not getting back to you till now... I figured once we have a document in the repo we can begin making pull requests against it.

@guybedford Please note #158

[MylesBorins]

Removing from agenda as we can now discuss the PR

[SMotaal]

@MylesBorins @guybedford I think we should close this, right?