Skip to content

Commit 71e9b30

Browse files
Add section on filing changes to existing phase 3 proposals (#609)
* Add section on filing changes to existing phase 3 proposals * Apply suggestions from code review Co-authored-by: Guy Bedford <guybedford@gmail.com> --------- Co-authored-by: Guy Bedford <guybedford@gmail.com>
1 parent 32390fc commit 71e9b30

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

Contributing.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,41 @@ Phases 4 and 5 are where a feature is finished and standardized. As WASI matures
109109
[proposal template]: https://github.com/WebAssembly/wasi-proposal-template
110110
[WASI meeting agenda]: https://github.com/WebAssembly/meetings/tree/main/wasi
111111
[WebAssembly CG's Phase Process]: https://github.com/WebAssembly/meetings/blob/main/process/phases.md
112+
113+
## Filing changes to existing phase 3 proposals
114+
115+
Extending existing phase 3 WASI proposals follows a different process than filing
116+
new proposals. Because the scope of a phase 3 proposal is already set, further
117+
changes to its APIs are tracked independently as phase 2 proposals behind an
118+
`@unstable` gate in WIT. Once an extension is sufficiently developed, and meets
119+
the phase 3 criteria, it must go through a vote in the WASI SG to reach
120+
phase 3. Once that's done, the `@unstable` gate can be replaced with `@since`,
121+
and the extension can be included in a future WASI release.
122+
123+
To submit an extension to an existing phase 3 WASI proposal, the following
124+
process should be followed:
125+
126+
1. File a PR to a WASI proposal repo with the feature extensions behind an
127+
`@unstable` gate. Feature gate names all exist in a shared namespace, so they
128+
should be prefixed with the parent proposal name. An unstable "timezone"
129+
feature for the "clocks" proposal should be named `clocks-timezone`.
130+
2. Accepting changes to proposals is done at the discretion of the proposal
131+
champions. They will review and work with the PR submitter to get it to a
132+
state where it can be merged, or explain why the extension is presently not
133+
the right fit for the existing proposal.
134+
3. Once the champion is ready to merge the proposal, they will submit a PR to
135+
the WASI repository (this repository) to file for a new phase 2 feature.
136+
4. Once the feature is tracked on the WASI repository the champion can now merge
137+
the extension. This would also be a good time to inform the WASI SG that an
138+
extension has landed - in the interest of keeping relevant parties informed.
139+
5. Implementers should now be free to begin implementing the extension behind
140+
feature flags. The goal at this phase is to implement and iterate on the
141+
extension until it is ready to advance to phase 3.
142+
6. Once the champion believes the phase 3 advancement criteria are met, they
143+
should bring it to the WASI SG for a vote.
144+
7. Once the proposal is voted to advance to phase 3, the `@unstable` gate should
145+
be replaced with a `@since` gate containing the version of the next WASI
146+
release. It is encouraged to preserve the `feature` field in the `@since` gate to
147+
help the transition from the `@unstable` feature to the newly stabilized
148+
`@since` gate.
149+
8. The proposal is now ready to be released as part of the next WASI version.

0 commit comments

Comments
 (0)