-
Notifications
You must be signed in to change notification settings - Fork 259
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
pchickey
merged 4 commits into
WebAssembly:main
from
sunfishcode:sunfishcode/contributing
Sep 7, 2023
Merged
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
9a4cef5
Rebase the Phase Process description on the CG's current process
sunfishcode 94c1a27
Fix a typo.
sunfishcode 685227f
Rename "phase 4 acceptance criteria" to "portability criteria".
sunfishcode c9bda75
Re-introdce "two or more implementations" language.
sunfishcode File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
* 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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) There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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"
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.