Should a formal spec be required for phase 3?

Open
#243 5 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
wasm

Research direction

Start with the phase 2 and phase 3 requirements quoted in the issue, then review the linked Google Docs overview. Compare the current process with the proposed formal-spec requirement. Done means a clear decision on whether to amend the phase 3 requirements, with the process description updated if the proposal is accepted.

Written by the indexing model from the issue text.

Description

The current requirements for phase 2 are:

  • Precise and complete overview document is available in a forked repo around which a reasonably high level of consensus exists.
  • Updates to the actual spec document, test suite, and reference interpreter are NOT yet required.

The current requirements for phase 3 are:

  • Test suite has been updated to cover the feature in its forked repo.
  • The test suite should run against some implementation, though it need not be the reference interpreter.
  • Updates on the actual spec document and reference interpreter are NOT yet required (but can happen earlier).

The purpose of phase 2 is for at least one engine to implement the feature, enough to produce a reasonable test suite for phase 3. On the other hand, the purpose of phase 3 is for all engines to implement the feature - but they are forced to do so without a formal spec, and must make do with a "precise and complete overview document". Personally, having gone through much of the Wasm GC implementation with nothing to guide me but a linked list of Google Docs, I would have MUCH PREFERRED a formal spec to follow.

I presume the lack of spec requirement was because, in the past, the formal spec was very burdensome to update. But these days much of the tedium is handled by SpecTec and we have AIs that can catch bugs and slog through macro minutia. I find it much easier these days to keep the formal spec up to date.

Should we amend the process to require a complete formal spec by phase 3?

Dominant language
Python
Stars
1.1k
Forks
78
PR merge metrics
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from WebAssembly/proposals

All issues in WebAssembly/proposals

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.