1 of 8

Documenting whether a proposal is ready to ship

Daniel Ehrenberg

Bloomberg

January 2023 TC39 meeting

2 of 8

The TC39 stage process

  • Stage 1: An idea under discussion
  • Stage 2: We want to do this, and we have a first draft
  • Stage 3: Basically final draft; ready to go
  • Stage 4: 2+ implementations, tests ⇒ standard

3 of 8

What happens between Stage 3 and 4?

  • Various engines implement the specification
  • Test262 tests are written and landed
  • Various bugs are discovered in the course of that, and resolved
  • Integration with environments (e.g., Node, HTML) is elaborated�(if not done already)
  • The committee may come to consensus on a normative�(just as it may for the finished spec)
  • Some engines ship the proposal
  • Some of these are embedded in browsers

4 of 8

When does it make sense to ship?

  • Usually, a proposal is ready to ship when it reaches Stage 3
  • Occasionally, JS engines may wait to ship Stage 3 proposals
  • Possible reasons an implementation may hold back:
    • Stage 3 had conditional consensus, and the conditions aren’t met yet
    • The champion group plans to fix certain known issues,�but hasn’t done so yet
    • If host environment integration isn’t done,�the proposal can’t ship in that host environment
    • One engine may wait for implementation experience from another engine

5 of 8

Why are we discussing this now?

  • We’ve long had some Stage 3 proposals that are not ready to ship
    • Classic example: Temporal
  • At the same time, Stage 3 is usually stable, and should be understood so.

​

  • Now: Safari announced it was shipping ShadowRealm without certain essential features (e.g., HTML integration)

​

  • Goal: Document clearly when essential pieces are missing, to reduce the chance of creating a differing implementations
    • No one wants a compatibility matrix

6 of 8

Proposal: Document clearly: “this isn’t ready to ship”

  • The strong default is, Stage 3 means ready to ship
  • For the exceptional cases, document that the proposal isn’t ready to ship

​

  • Add a column in the proposals repo, for Stage 3 proposals
  • Set by the proposal champions
  • Non-binding: engines can always do what they want
    • Both shipping earlier and later

7 of 8

Feedback I’ve gotten so far

  • Some like this lightweight documentation-oriented proposal.

​

  • Some say, there should be a process for settling disputes where the champion says something is ready to ship, and others in committee disagree
    • I’m wary of a process risking another pass of consensus-seeking between Stage 3 and 4
    • Codename for this formalization: “Stage 3.5”

​

  • Some say, “Stage 2.5” could be intermediate, and Stage 3 is ready to ship
    • But, what to do if something relatively small comes up after Stage 3? (as in Temporal)�Demoting would often be an excessive barrier to progress

8 of 8

Proposed next steps

  • I suggest we start with “not ready to ship” be considered documentation from the champion
    • Dispute resolution mechanisms could be a following step, based on this PR’s foundation

Stage 3 proposals which are not ready to ship by littledan · Pull Request #123 · tc39/how-we-work (github.com)

Consensus?