Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rebase the Phase Process description on the CG's current process #549

Merged
merged 4 commits into from
Sep 7, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 77 additions & 27 deletions Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,58 +3,108 @@
Interested in participating? Please follow
[the same contributing guidelines as the design repository][].

[the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/master/Contributing.md
[the same contributing guidelines as the design repository]: https://github.com/WebAssembly/design/blob/master/Contributing.md

Also, please be sure to read [the README.md](README.md) for this repository.

## Championing a Proposal
To contribute to an [existing proposal](https://github.com/WebAssembly/WASI/blob/main/Proposals.md),
refer to the linked proposal repository.

If you want to champion a new proposal, here's what you need to do in each phase:
The start a new proposal, the first step is to file an issue in the
[WASI repository](https://github.com/WebAssembly/WASI/issues) presenting
the idea. A good API proposal should discuss the scope of the API,
the use cases, and the places it would be expected to be implemented.
Then proceed with the rest of the steps in phase 0 described below.

### Phase 0: Gauge interest
If you have any questions about any step of the process, please reach out
to one of the WASI Subgroup (SG) chairs.

You have an idea for an API. To see whether others are interested in pursuing the idea, you should work up a rough description of the API and post it somewhere that is publicly visible. This could be in the WASI issue queue, or in a gist or as its own repo. You can use the [proposal template] if you like, but it's not required in this phase.
## The Phase Process

Once you've done this, you can optionally have the subgroup discuss the idea by adding a discussion item to the [WASI meeting agenda].
The following process is modeled after [WebAssembly CG's Phase Process],
though it differs in several areas, to reflect the unique needs of APIs.

Once you feel ready, you can add a vote to the [WASI meeting agenda] to move to the next stage.
Something is out-of-scope if it doesn't fit the [WASI Subgroup's charter](https://github.com/WebAssembly/WASI/blob/main/Charter.md) and there's agreement that the charter should not be amended to cover the proposal.

### Phase 1: Write spec text
In general, the process moves forward through a series of numbered phases.
However, if issues are uncovered or consensus devolves,
proposals should back up to the appropriate prior step.

At this point, the WASI SG chair will create a new repo for the proposal in the WebAssembly GitHub org. This will follow the conventions of the [proposal template] and [Wit in WASI](docs/WitInWasi.md). If you have any questions about how to fill in the spec template, you can reach out to the WASI SG chair.
No vote is required for a proposal to enter phase 0. To advance from one phase
to another, a vote proposing the advancement is added to a
[WASI Subgroup meeting](https://github.com/WebAssembly/meetings/tree/main/wasi) agenda
through a pull request, and the SG votes on whether to approve it, evaluating
whether the new phase's entry requirements have been met.

As part of moving to the next phase, the champions need to define the acceptance criteria for Phase 4. This is because WASI includes APIs that cover a diversity of different domains and use cases, so the acceptance criteria can be very different between different proposals.
### 0. Pre-Proposal [Individual Contributor]

Some examples of potential criteria:
Entry requirements:

- multiple independent production implementations
- implementations on multiple host platforms
- polyfill implementations
- bindings in toolchains and libraries
* A WASI Subgroup (SG) member has an idea. Notably, no SG vote is required to begin phase 0.

Note: portability requirements may vary between proposals, as not all features will necessarily make sense in all host environments.
During this phase:

With all this in place, you can add a vote to [WASI meeting agenda] to move to the next stage.
1. An issue is filed on the [WASI repository](https://github.com/WebAssembly/WASI/issues) to present the idea.
1. Discussion on the API occurs on the issue.
1. A champion or champions emerge. They may add the proposal to the [proposal list](https://github.com/WebAssembly/WASI/blob/main/Proposals.md) at phase 0.
1. The champion(s) put together a description of the API in their own GitHub repository or on the issue. You can use the [proposal template] if you like, but it's not required in this phase.

### Phase 2: Work with implementers to prototype and refine the design
### 1. Feature Proposal [WASI Subgroup]

At this point, you should be prototyping the API to make sure it works in practice, and you should develop a test suite which can be used by other implementations to validate their spec compliance.
Entry requirements:

Once the implementation has stabilized, it's again time to add a vote to [WASI meeting agenda] to move to the next stage.
* There is general interest within the SG in this API.
* The SG believes the API is in-scope and will plausibly be workable.

### Phase 3: Validate the design through multiple implementations
During this phase:

At this point, you'll need to get more implementers involved. How many implementations you need depends on the Phase 4 acceptance criteria that you set in Phase 2.
1. If the proposal is not already listed, it should be added to the [proposal list](https://github.com/WebAssembly/WASI/blob/main/Proposals.md) at this time.
1. A new repository, forking the [proposal template] repo, is created by one of the SG chairs, or transferred to the WebAssembly organization by the champion.
1. The champion will attempt to reach broad consensus in the Subgroup.
1. Pull requests and issues are used to iterate on the design of the API. Specifically, an overview document must be produced that specifies the API with reasonably precise and complete language before attempting to move to phase 2 (meaning it is sufficiently precise to be implemented following this description, without obvious holes or ambiguities).
1. If relevant to demonstrate the viability of a API, prototype implementations of the API are implemented by interested embedders (possibly on a branch).

You may need to make changes in response to implementer feedback, but we expect the API to be pretty stable by this point. If implementors uncover especially challenging design issues, the proposal may be sent back to Phase 2 for more development.
Additionally during this phase:

Once the implementations are in place, you can add the final WASI SG vote to [WASI meeting agenda]. After this, the proposal advances to a vote in the broader WebAssembly CG.
* The champions define the *portability criteria* for Phase 4.

### Phases 4 & 5: Push it over the finish line
This is intended to translate the spirit of the CG Phase Process' "Two or more Web VMs" requirement to meet WASI's needs. The criteria should establish at least:
- Two or more implementations: Each proposal should say what kinds of implementations.
- Portability: WASI APIs should be portable, however that can mean different things to different use cases, and no one definition covers everything. Consequently, each proposal should define criteria establishing its specific portability requirements.
- Practicality: It's important that WASI APIs be implementable and usable in real-world use cases, so each proposal should define criteria establishing a sufficient level of confidence.
- Testing: APIs will have different needs in terms of environments needed to test them, so each proposal should define criteria establishing what form the testing will take.

The specific process in Phases 4 and 5 will be determined when we have a proposal ready for them.
### 2. Feature Description Available [WASI Subgroup]

Note: While we mostly follow the [WebAssembly CG's Phase Process], the requirements around Web VM implementation, formal notation and the reference interpreter don't apply in the context of WASI.
Entry requirements:

* The portability criteria are documented in the proposal.
* Precise and complete overview document is available in a proposal repo around which a reasonably high level of consensus exists.
* A [wit](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) description of the API exists.
* All dependencies of the wit description must have reached phase 2.

During this phase:

* One or more implementations proceed on prototyping the API.
* A plan is developed for how the portability criteria will be met.

## 3. Implementation Phase [WASI Subgroup]

Entry requirements:

* The portability criteria must be either met or there must be a plan for how they're expected to be met.
* All dependencies of the wit descriptions must have reached phase 3.

During this phase, the following proceeds in parallel:

* Implementations are built
* Toolchains, libraries, and other tools using the API are built
* Remaining open questions are resolved.
* The plan for satisfying the portability criteria is followed, though the plan may change over time.

### Phases 4 & 5: To be determined

Phases 4 and 5 are where a feature is finished and standardized. As WASI matures, the WASI Subgroup will coordinate with its parent WebAssembly Community Group and the WebAssembly Working Group to define a process for standardization.

[proposal template]: https://github.com/WebAssembly/wasi-proposal-template
[WASI meeting agenda]: https://github.com/WebAssembly/meetings/tree/main/wasi
Expand Down