Conversation
|
|
||
| This repo contains the WinterTC Runtime Keys ECMA Technical Report source and build tooling. | ||
|
|
||
| To get started, run `npm install` to install project dependencies |
There was a problem hiding this comment.
nit: maybe we want to recommend using npm ci instead? (to avoid modifying the existing lock file)
spec.html
Outdated
| <ul> | ||
| <li>Avoid being too similar to existing keys</li> | ||
| <li>Avoid similarity to common English words or offensive terms</li> | ||
| <li>Avoid being too generic or similar to general terminology such as "Web Runtimes", "Edge Runtimes", or "JavaScript Runtimes"</li> |
There was a problem hiding this comment.
Avoid being too generic or similar to general terminology such as "Web Runtimes", "Edge Runtimes", or "JavaScript Runtimes"
Is this a distinction for the name or the key? For example, there is this existing one (which may be "grandfathered" in, as I am assuming this is not retro-active)
{
"organization": "Azion",
"name": "Edge Functions",
"key": "azion",
"description": "Azion Edge Functions for ultra-low latency, edge-native applications, built with open standards for secure, high-performance serverless computing.",
"website": "https://www.azion.com/en/products/edge-functions/",
"repository": null,
"deprecated": false
},Would we maybe want to recommend existing entries to update?
There was a problem hiding this comment.
suggesting Azion update their name to "Azion Edge Functions" seems like a not-unreasonable move
There was a problem hiding this comment.
Yeah I believe the justification was that we didn't care about the name field. In fact, Netlify uses the exact same name, "Edge Functions". What really matters is the key since that is what everyone actually uses. Vercel, React, Arvan, Fastly, and Alibaba are other examples of names that are fairly ambiguous.
gesa
left a comment
gesa
left a comment
There was a problem hiding this comment.
Cloudflare's workerd is not ideal, it's too late to ask them to change that right?
| <emu-note> | ||
| <p>This section is generated from the machine-readable registry data (see <emu-xref href="#sec-machine-readable-registry"></emu-xref>). In the build process, this content should be dynamically generated from <code>runtime-keys.json</code>.</p> | ||
| </emu-note> | ||
|
|
There was a problem hiding this comment.
| <emu-note> | |
| <p>This section is generated from the machine-readable registry data (see <emu-xref href="#sec-machine-readable-registry"></emu-xref>). In the build process, this content should be dynamically generated from <code>runtime-keys.json</code>.</p> | |
| </emu-note> |
To clarify, you would remove the generated table from the version control markup once we're happy with the overall document, right?
There was a problem hiding this comment.
Yes - apologies for any confusion around that. The spec.html would be the like raw document that then the generated table would be injected into, when eventually a build script exists. I just had it in there to start with so we could get a sense for things.
There was a problem hiding this comment.
| <emu-note> | |
| <p>This section is generated from the machine-readable registry data (see <emu-xref href="#sec-machine-readable-registry"></emu-xref>). In the build process, this content should be dynamically generated from <code>runtime-keys.json</code>.</p> | |
| </emu-note> | |
| <emu-note> | |
| <p>This section is generated from the machine-readable source data (see <emu-xref href="#sec-machine-readable-source"></emu-xref>).</p> | |
| </emu-note> | |
I can see adding a line here about how a reader can access the machine-readable code with a URL maybe? Or something that effect? But I don't think the sentence about the build process totally works.
| <li><strong>Organization</strong> (required): The organization or individual responsible for the runtime</li> | ||
| <li><strong>Name</strong> (required): The human-readable name of the runtime</li> | ||
| <li><strong>Key</strong> (required): The unique string identifier</li> | ||
| <li><strong>Description</strong> (required): A brief description of the runtime</li> |
There was a problem hiding this comment.
🤔 Should this use more precision than "brief" ? A maximum character length maybe? (similarly should all fields have a character length limit?)
There was a problem hiding this comment.
Also I think "required" is fine here, but if the secretariat raises any concerns, maybe we switch to "mandatory"?
|
What is wrong with Contrary to |
gesa
left a comment
gesa
left a comment
There was a problem hiding this comment.
For consistency, use TC55 when referring to the TC, and use WinterTC55 when referring to the GitHub org.
I am v excited about this TR. Now I need to write the ecmarkup to generate it as not-a-standard
| </emu-note> | ||
|
|
||
| <emu-note> | ||
| <p>Inclusion in this Report does not imply that the specified runtime is conformant with any ECMA TC55 specification, including the WinterTC Minimum Common API. Inclusion does not imply endorsement of any kind.</p> |
There was a problem hiding this comment.
| <p>Inclusion in this Report does not imply that the specified runtime is conformant with any ECMA TC55 specification, including the WinterTC Minimum Common API. Inclusion does not imply endorsement of any kind.</p> | |
| <p>Inclusion in this Report does not imply that the specified runtime is conformant with any Ecma specification, including the WinterTC Minimum Common API. Inclusion does not imply endorsement of any kind.</p> |
There was a problem hiding this comment.
This suggestion seems odd, since the definition for "ECMAScript runtime" requires conformance with ECMA-262.
|
|
||
| <emu-clause id="sec-runtime-source"> | ||
| <h1>Canonical source for runtime keys</h1> | ||
| <p>The following table lists all previously recorded runtime keys, sorted alphabetically by organisation.</p> |
There was a problem hiding this comment.
| <p>The following table lists all previously recorded runtime keys, sorted alphabetically by organisation.</p> | |
| <p>The following table lists runtime keys submitted to TC55 and reviewed by the Committee, sorted alphabetically by organisation.</p> |
I feel like this line is a tightrope
| <emu-note> | ||
| <p>This section is generated from the machine-readable registry data (see <emu-xref href="#sec-machine-readable-registry"></emu-xref>). In the build process, this content should be dynamically generated from <code>runtime-keys.json</code>.</p> | ||
| </emu-note> | ||
|
|
There was a problem hiding this comment.
| <emu-note> | |
| <p>This section is generated from the machine-readable registry data (see <emu-xref href="#sec-machine-readable-registry"></emu-xref>). In the build process, this content should be dynamically generated from <code>runtime-keys.json</code>.</p> | |
| </emu-note> | |
| <emu-note> | |
| <p>This section is generated from the machine-readable source data (see <emu-xref href="#sec-machine-readable-source"></emu-xref>).</p> | |
| </emu-note> | |
I can see adding a line here about how a reader can access the machine-readable code with a URL maybe? Or something that effect? But I don't think the sentence about the build process totally works.
|
|
||
| <emu-clause id="sec-adding-entries"> | ||
| <h1>Proposing new runtime key entries</h1> | ||
| <p>All ECMAScript runtimes are welcome to propose a key for inclusion in this Report, subject to the attributes specified in <emu-xref href="#sec-runtime-key-structure"></emu-xref>. Runtimes which contribute to this Report are encouraged, but not required, to participate in Ecma TC55.</p> |
There was a problem hiding this comment.
| <p>All ECMAScript runtimes are welcome to propose a key for inclusion in this Report, subject to the attributes specified in <emu-xref href="#sec-runtime-key-structure"></emu-xref>. Runtimes which contribute to this Report are encouraged, but not required, to participate in Ecma TC55.</p> | |
| <p>All ECMAScript runtimes are welcome to propose a key for inclusion in this Report, subject to the structure as described in <emu-xref href="#sec-runtime-key-structure"></emu-xref>. Runtimes which contribute to this Report are encouraged, but not required, to participate in Ecma TC55.</p> |
| <emu-clause id="sec-proposal-process"> | ||
| <h1>Proposal process</h1> | ||
| <emu-alg> | ||
| 1. The proposer creates a pull request in the <a href="https://github.com/WinterTC55/runtime-keys">runtime-keys repository</a>. |
There was a problem hiding this comment.
| 1. The proposer creates a pull request in the <a href="https://github.com/WinterTC55/runtime-keys">runtime-keys repository</a>. | |
| 1. The proposer creates a pull request in the <a href="https://github.com/WinterTC55/runtime-keys">WinterTC55/runtime-keys GitHub repository</a>. |
not sure how important the WinterTC55 part is, but being explicit about GItHub is.
| </emu-clause> | ||
| </emu-clause> | ||
|
|
||
| <emu-annex id="sec-machine-readable-source"> |
There was a problem hiding this comment.
| <emu-annex id="sec-machine-readable-source"> | |
| <emu-annex id="sec-machine-readable-source" normative> |
|
|
||
| <emu-annex id="sec-example-usage"> | ||
| <h1>Example usage</h1> | ||
| <p>This annex provides non-normative examples of how runtime keys may be used in practice.</p> |
There was a problem hiding this comment.
| <p>This annex provides non-normative examples of how runtime keys may be used in practice.</p> | |
| <p>This Annex provides informative examples of how runtime keys may be used in practice.</p> |
| <body> | ||
| <pre class="metadata"> | ||
| title: Runtime Keys | ||
| status: draft |
There was a problem hiding this comment.
| status: draft | |
| status: draft-TR |
| <emu-clause id="sec-scope"> | ||
| <h1>Scope</h1> | ||
|
|
||
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focusses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to be used in web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> |
There was a problem hiding this comment.
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focusses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to be used in web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> | |
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focuses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to be used in web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> |
my b
|
|
||
| <emu-clause id="term-runtime"> | ||
| <h1><dfn variants="ECMAScript runtimes">ECMAScript runtime</dfn></h1> | ||
| <p>implementation of the ECMA-262 ECMAScript langauge specification</p> |
There was a problem hiding this comment.
| <p>implementation of the ECMA-262 ECMAScript langauge specification</p> | |
| <p>implementation of the ECMA-262 ECMAScript language specification</p> |
also my b
|
@Ethan-Arrowood Bringing your notes from my PR into this primary PR
I'm deeply conflicted about the spelling of organisation within the JSON. Ecma does formally use Oxford GB English, but when it comes to code, designers have historically opted for en-US spellings. |
| <emu-clause id="sec-scope"> | ||
| <h1>Scope</h1> | ||
|
|
||
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focusses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to be used in web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> |
There was a problem hiding this comment.
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focusses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to be used in web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> | |
| <p>Runtime keys provide a consistent and predictable mechanism for identifying ECMAScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. This document focusses on providing informative identifiers primarily for web servers, though other ECMAScript server environments may find it useful. These keys are not intended to represent web browsers, which should be referenced by other mechanisms such as the browserslist project.</p> |
|
|
||
| <emu-clause id="term-runtime"> | ||
| <h1><dfn variants="ECMAScript runtimes">ECMAScript runtime</dfn></h1> | ||
| <p>implementation of the ECMA-262 ECMAScript langauge specification</p> |
There was a problem hiding this comment.
By this definition, JS engines such as V8 would qualify as a runtime.
| <li>any other existing runtime key in this Report, or</li> | ||
| <li> | ||
| any existing Browserslist <em>browser</em> entries. | ||
| <emu-note>This explicitly excludes references to <em>server</em> runtimes within Browserslist.</emu-note> |
There was a problem hiding this comment.
Should this link to https://github.com/browserslist/browserslist?tab=readme-ov-file#browsers? Or can we even link to a github readme that we don't control from a technical report?
|
|
||
| <emu-clause id="sec-runtime-existence"> | ||
| <h1>Runtime existence validation</h1> | ||
| <p>The runtime environment represented by a key must actually exist, whether as open source, source-available, or proprietary software. Entries in this Report exist to identify real runtimes, not to reserve names for future projects.</p> |
There was a problem hiding this comment.
What about organization-internal runtimes, such as Bloomberg's Rapid and R+? Those "actually exist" and are proprietary software, but I don't think people outside of Bloomberg (or their contractors) could verify that they exist.
I think we should probably exclude those. But the wording for that should probably not exclude e.g. proprietary runtimes that are available as SaaS but which you can't download.
| </emu-note> | ||
|
|
||
| <emu-note> | ||
| <p>Inclusion in this Report does not imply that the specified runtime is conformant with any ECMA TC55 specification, including the WinterTC Minimum Common API. Inclusion does not imply endorsement of any kind.</p> |
There was a problem hiding this comment.
This suggestion seems odd, since the definition for "ECMAScript runtime" requires conformance with ECMA-262.
4 participants
Authors an ECMA Technical Report for the future of runtime-keys work.
Closes: #23
Note: this is still heavily WIP; you're welcome to leave feedback but please know I'm still actively working on certain parts. This will be discussed at upcoming WinterTC meetings (first one will be January 23rd), so please attend those if you want to participate in the discussion.