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 2 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
103 changes: 76 additions & 27 deletions Contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,58 +3,107 @@
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 acceptance 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:
- 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 phase 4 acceptance criteria are documented in the proposal.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it meant to be phase 3? There is a reference to the acceptance criteria there, while phase 4 seems to be "TBD"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for bringing this up.

The "phase 4 acceptance criteria" are defined here, and are attended to be a substitute for the "two Web VMs" requirement in the corresponding phase 4 in the CG process.

Phase 4 in the CG process means "the feature is done and handed off to the WG for proper standardization". For WASI, we aren't ready for anything analogous to that yet; we're still working on what we're calling "Preview 2".

So, this PR proposes defining "Preview 2" as requiring proposals be at only phase 3. But, we do want Preview 2 proposals to have something of the level of confidence that "Two Web VMs" have, so we added this language about the "phase 4 acceptance criteria" as a Preview 2 requirement.

Does that clarify it?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it's just me, but currently "phase 4 acceptance criteria" sounds like "acceptance criteria to a stage we haven't yet defined", also logically requiring phase 4 before phase 3 doesn't make very strong sense. Maybe have the criteria point to phase 3 officially or give them a phase-neutral name (how about "Preview 2 acceptance criteria", since that is the end goal)? Or define a phase 4?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we renamed the "phase 4 acceptance criteria" to the "portability criteria", would that make it clear?

Copy link

@penzn penzn Aug 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be more clear that way, I think. Oh wait, but this removes explicit 'multiple implementations' requirements from the old doc - that was hard to see, the diff seems to be mixing sections of the doc. Is it implied or not necessary?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've now performed the rename, here and in #550.

Wrt your edit, I've also now re-introduce "two or more implementations" language. That was previously only an example, but it does seem worth having, even if we have to leave it up to proposals to define what kinds of implementations are needed.

* 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 phase 4 acceptance criteria will be met.

## 3. Implementation Phase [WASI Subgroup]

Entry requirements:

* The phase 4 acceptance criteria must be either met or there must be a plan for how they're expected to be met.
Copy link

@penzn penzn Aug 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be phase 3? (this is inside 'phase 3' section of the doc)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's written as intended; see my comment above.

* 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 phase 4 acceptance 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