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:

Pick Format: GD
Determine Initial Structure: taxonomy-like
Initial Draft (@SMotaal)
Create terminology branch (@SMotaal)
Create Terminology.md Create Terminology.md #158

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?

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

…

On May 23, 2018, at 2:22 PM, Benjamin Gruenbaum ***@***.***> 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 <#119 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAecVw18HUjcvHcPx4MW8q04n9V9CslUks5t1ajqgaJpZM4UK85g>.

@benjamingr

@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.

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

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.

@GeoffreyBooth

@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.

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.

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.

@SMotaal

@SMotaal I've attempted to begin population by starting with the most controversial term (transparent interop). It is an attempt to resolve #138

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.

@SMotaal

@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.

@devsnek

- 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.

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.

@guybedford

@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.

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.

@demurgos

@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

Removing from agenda as we can now discuss the PR

@MylesBorins

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

Navigation Menu

Repository navigation

Initiative: Terminology / Historical Decisions documents #119

15 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Initiative: Terminology / Historical Decisions documents #119

Description

Activity

benjamingr commented on May 23, 2018

MylesBorins commented on May 23, 2018

SMotaal commented on May 23, 2018

bmeck commented on May 24, 2018

GeoffreyBooth commented on May 24, 2018

bmeck commented on May 24, 2018

GeoffreyBooth commented on May 24, 2018

SMotaal commented on May 28, 2018

SMotaal commented on May 30, 2018

devsnek commented on May 30, 2018

15 remaining items

SMotaal commented on Jun 23, 2018

robpalme commented on Jun 26, 2018

guybedford commented on Jul 18, 2018

guybedford commented on Jul 18, 2018

demurgos commented on Jul 19, 2018

SMotaal commented on Jul 19, 2018

SMotaal commented on Jul 19, 2018

demurgos commented on Jul 19, 2018

SMotaal commented on Jul 25, 2018

MylesBorins commented on Jul 31, 2018

SMotaal commented on Oct 7, 2018

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions