Edits to align with Ecma house style #31
Conversation
gesa
left a comment
gesa
left a comment
There was a problem hiding this comment.
@Ethan-Arrowood I hope this gives you something useful to work from! Let me know if you want to collab on any further edits
| <emu-intro id="sec-intro"> | ||
| <h1>Introduction</h1> | ||
|
|
||
| <p>This Technical Report defines a canonical source for identifiers of unique ECMAScript runtime environments, known as <em>runtime keys</em>.</p> |
There was a problem hiding this comment.
Intro section just exists to indicate to a reader whether or not this is the TR they were looking for
|
|
||
| <emu-clause id="sec-description"> | ||
| <h1>Description</h1> | ||
| <p>A <dfn>runtime key</dfn> is a unique string identifier that represents a specific JavaScript runtime environment. Runtime keys provide a standardized mechanism for identifying JavaScript runtimes in a variety of contexts, including but not limited to project configuration files, package manifests, conditional exports, and runtime detection mechanisms. These keys are meant to particularly represent server environments. Browsers should still be generally referenced by other mechanisms such as the browserslist project.</p> |
There was a problem hiding this comment.
I was on the fence about removing "standardised", since it's a description and not a claim about the document itself.
| <li>The normative requirements for runtime keys</li> | ||
| <li>The governance process for adding and modifying registry entries</li> | ||
| </ul> | ||
| <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.
I narrowed the scope a bit to align more closely with the TC's charter. The phrase from the charter is
…improving interoperability across multiple ECMAScript environments which expand beyond web browsers, specifically web servers
| <li>the canonical source of runtime keys and associated metadata,</li> | ||
| <li>guidance for future ECMAScript runtimes to submit runtime keys, and</li> | ||
| <li>TC55's governance process for adding and modifying runtime keys to the Report.</li> |
There was a problem hiding this comment.
TRs are informative only, so they do not include normative requirements. I think my wording (especially on point two) is clumsy though, definitely needs work.
| </ul> | ||
|
|
||
| <emu-note> | ||
| <p>This specification does not define <em>how</em> runtime keys should be used by tools or libraries. The purpose of this registry is to prevent conflicts and provide a reliable, authoritative source of runtime identifiers that the community can build tooling around.</p> |
There was a problem hiding this comment.
This was a little more prescriptive than the rest of the document implies, so I cut the last sentence fragment
| 1. At least two WinterTC members not affiliated with the runtime must approve the pull request. | ||
| 1. The modification must be formally approved at a WinterTC plenary meeting. | ||
| 1. After plenary approval, designated editors merge the pull request. | ||
| 1. The proposal continues as described starting at step <emu-xref href="#step-approval-process"></emu-xref> in the approval process. |
There was a problem hiding this comment.
I added these x-references for consistency, but if you think it's better with the steps written out in each subclause, that's probably fine
| <p>The authoritative, machine-readable form of the runtime key registry is maintained as a JSON file: <code>runtime-keys.json</code>.</p> | ||
| <emu-annex id="sec-machine-readable-source"> | ||
| <h1>Machine-readable canonical source</h1> | ||
| <p>The authoritative, machine-readable form of the runtime key source is maintained as a JSON file: <code>runtime-keys.json</code>.</p> |
| <h1>JSON Schema</h1> | ||
| <p>The registry JSON file conforms to the following structure:</p> | ||
| <h1>JSON schema</h1> | ||
| <p>The runtime keys source data JSON file conforms to the following structure:</p> |
| <emu-annex id="sec-biblio" back-matter> | ||
| <h1>Bibliography</h1> | ||
| <p> | ||
| ECMA-262, <i>ECMAScript® Language Specification</i><br /> |
There was a problem hiding this comment.
Since I added a term for "runtime" and offhandedly referenced ECMA-262, I added a biblio with this line. If you get rid of the definition of runtime or the mention of 262, go ahead and delete this section
|
|
||
| <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> |
whoops
| "watch": "ecmarkup --watch --verbose --lint-spec spec.html out.html" | ||
| }, | ||
| "devDependencies": { | ||
| "ecmarkup": "^22.0.0" |
There was a problem hiding this comment.
| "ecmarkup": "^22.0.0" | |
| "ecmarkup": "^23.0.2" |
while I was working on my review the 262 editors were hard at work releasing new versions of ecmarkup
|
Amazing! Thank you for this. I will review the comments soon and see how best to land this. I likely will land these changes directly into my draft branch and then we can continue iterating on isolated parts, but I'll make sure to review first before merging. And the top-level points you shared all sounds good to me. |
2 participants
@Ethan-Arrowood this your first draft is so good that I had the cognitive overhead to tackle house styles stuff, which I usually safe for far later drafts. I'm incredibly impressed, what a phenomenal start.
The below changes are just a starting point, not an ending one. Do not be afraid to further (aggressively even!) edit. I'll do a review with comments forthright so it's clear why some of the edits were made.
The most important notes here are: