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

sunfishcode · web-flow · commit 9ab5446ceee5 · 2023-09-07T09:33:24.000-07:00
* Rebase the Phase Process description on the CG's current process The [CG Phase Process document] has recently split out the entry requirements for each stage from the activities that happen within each stage, fixing an ambiguity about what happens before a stage and what happens within a stage. It also contains a number of generally useful updates. This PR updates the WASI Phase Process using wording derived from the CG Phase Process, adapting it to meet WASI's needs. The resulting process is roughly the same as the existing process, however I've made it more specific in a few areas: - Phase 2 requires a wit description. - Phase 3 requires there be a plan for how the phase 4 accpetance criteria will be met. [CG Phase Process document]: https://github.com/WebAssembly/meetings/blob/main/process/phases.md * Fix a typo. * Rename "phase 4 acceptance criteria" to "portability criteria". * Re-introdce "two or more implementations" language.
diff --git a/Contributing.md b/Contributing.md
@@ -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
