Documenting editorial conventions

[bakkot]

The editors should write down editorial conventions for the benefit of contributors and future editors, perhaps in tc39/how-we-work.

I've tried to automatically enforce some of them in ecmarkup. But there's plenty of others. Let's use this issue to collect them for now.

• Oxford spelling
• conventions for spec lists, and also conventions for Records
• when a PR is Editorial, Normative, or Meta (especially around spec bugs: I believe we have an unwritten rule along the lines of "if the spec is nonsensical or contradictory as written, but there is a plausible interpretation which is followed by all major engines, then it is Editorial". When it is coherent but does not match what we believe to be the clear intent, and engines follow that intent rather than the spec as written, we will mark it as Normative but not require consensus from plenary to merge (e.g.).)
• the format of preambles for various operations (Editorial: use consistent wording for abstract operation preambles #1914, Editorial: Standardize preambles for internal methods and concrete methods #1994)

[michaelficarra]

Might be a good use of GitHub's wiki feature? They can be configured so that only maintainers can make edits.

[bakkot]

Here's a good one: under what circumstances do we pre-declare our aliases? See e.g. #1908 (comment), #2221 (comment).

[bakkot]

As of #2547, we should also include the rules for completion records: use of ! / ? / Completion(...) for calls of completion-record-returning AOs, non-use of those things for non-completion-record-returning AOs.

[michaelficarra]

We prefer spec enums over strings/constructors/instrinsics where they are just being switched over (aka used as an enum). See tc39/ecma402#689

[bakkot]

We generally do validation first, then the happy path. So e.g. 1. If not in range, throw. 2. Return value., rather than 1. If in range, return value. 2. Throw.

[michaelficarra]

I've started work on this here: https://github.com/tc39/ecma262/wiki/Editorial-Conventions