Contributing to WASI

Interested in participating? Please follow the same contributing guidelines as the design repositorygithub.

Also, please be sure to read the README.md for this repository.

Labels

This repository uses a categorized label system inspired by the Rust project. Proposal labels use the P- prefix to identify which WASI proposal an issue or pull request relates to.

Proposal Labels (P-)

Pull requests that modify files in a proposal directory are automatically labeled by the labeler workflow.

Status Labels (S-)

Closing Issues

The issue tracker accumulates proposals and questions faster than any one person can act on them. Closing issues is a normal, healthy part of keeping issues usable. Our goal is to direct folks towards actionable steps, even when closing issues. That may be to a different project, a way to move forward in the proposal process, how to begin iterating, etc. Some best practices to follow:

• Lead with the destination. “This belongs in X” reads very differently from “this is out of scope,” even when the outcome is the same.
• Say reopening is welcome. Closing an issue may be a statement about current activity, and not a verdict on merit. Anyone, not only the reporter, may reopen.
• Summarize before closing anything with real discussion. Issues with substantive back-and-forth, should not be closed without a summary of where the discussion landed.

The templates below are a starting point. Please edit these template messages with specifics of the issue.

Contributing to Proposals

To contribute to an existing proposalgithub, refer to the linked proposal repository.

The start a new proposal, the first step is to file an issue in the WASI repository 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.

If you have any questions about any step of the process, please reach out to one of the WASI Subgroup (SG) chairs.

The Phase Process

The following process is modeled after WebAssembly CG’s Phase Processgithub, though it differs in several areas, to reflect the unique needs of APIs.

Something is out-of-scope if it doesn’t fit the WASI Subgroup’s chartergithub and there’s agreement that the charter should not be amended to cover the proposal.

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.

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 meetinggithub 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.

0. Pre-Proposal [Individual Contributor]

Entry requirements:

• A WASI Subgroup (SG) member has an idea. Notably, no SG vote is required to begin phase 0.

During this phase:

1. An issue is filed on the WASI repository to present the idea.
2. Discussion on the API occurs on the issue.
3. A champion or champions emerge. They may add the proposal to the proposal listgithub at phase 0.
4. The champion(s) put together a description of the API in their own GitHub repository or on the issue. You can use the proposal templategithub if you like, but it’s not required in this phase.

1. Feature Proposal [WASI Subgroup]

Entry requirements:

• There is general interest within the SG in this API.
• The SG believes the API is in-scope and will plausibly be workable.

During this phase:

1. If the proposal is not already listed, it should be added to the proposal listgithub at this time.
2. A new repository, forking the proposal templategithub repo, is created by one of the SG chairs, or transferred to the WebAssembly organization by the champion.
3. The champion will attempt to reach broad consensus in the Subgroup.
4. 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).
5. If relevant to demonstrate the viability of a API, prototype implementations of the API are implemented by interested embedders (possibly on a branch).

Additionally during this phase:

• The champions define the portability criteria for Phase 4.

  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.

2. Feature Description Available [WASI Subgroup]

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 witgithub description of the API exists.
• All dependencies of the wit description must have reached phase 2.
• The wit description must be available from an OCI registry, with the OCI tag matching the package version string in the wit.

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.

Filing changes to existing phase 3 proposals

Extending existing phase 3 WASI proposals follows a different process than filing new proposals. Because the scope of a phase 3 proposal is already set, further changes to its APIs are tracked independently as phase 2 proposals behind an @unstable gate in WIT. Once an extension is sufficiently developed, and meets the phase 3 criteria, it must go through a vote in the WASI SG to reach phase 3. Once that’s done, the @unstable gate can be replaced with @since, and the extension can be included in a future WASI release.

To submit an extension to an existing phase 3 WASI proposal, the following process should be followed:

1. File a PR to a WASI proposal repo with the feature extensions behind an @unstable gate. Feature gate names all exist in a shared namespace, so they should be prefixed with the parent proposal name. An unstable “timezone” feature for the “clocks” proposal should be named clocks-timezone.
2. Accepting changes to proposals is done at the discretion of the proposal champions. They will review and work with the PR submitter to get it to a state where it can be merged, or explain why the extension is presently not the right fit for the existing proposal.
3. Once the champion is ready to merge the proposal, they will submit a PR to the WASI repository (this repository) to file for a new phase 2 feature.
4. Once the feature is tracked on the WASI repository the champion can now merge the extension. This would also be a good time to inform the WASI SG that an extension has landed - in the interest of keeping relevant parties informed.
5. Implementers should now be free to begin implementing the extension behind feature flags. The goal at this phase is to implement and iterate on the extension until it is ready to advance to phase 3.
6. Once the champion believes the phase 3 advancement criteria are met, they should bring it to the WASI SG for a vote.
7. Once the proposal is voted to advance to phase 3, the @unstable gate should be replaced with a @since gate containing the version of the next WASI release. It is encouraged to preserve the feature field in the @since gate to help the transition from the @unstable feature to the newly stabilized @since gate.
8. The proposal is now ready to be released as part of the next WASI version.

Adopting Component Model features

WASI APIs are defined in terms of the Component Modelgithub proposal, which develops its own features like new WIT syntax, types, and canonical ABI functionality behind gated featuresgithub. When a WASI API depends on one of these features, every runtime and toolchain that implements that WASI release must also implement the underlying Component Model feature. Adding such a dependence is therefore an explicit, per-feature decision made by the WASI Subgroup, following a process similar to graduating an @unstable feature gate to @since described above.

A Component Model feature is only eligible for adoption once it is stable:

• The feature’s design is complete and no further breaking changes are expected.
• The feature has been through a phase of iteration and feedback: it has been implemented in multiple runtimes and toolchains, exercised by real usage (for example, by WASI proposals experimenting with it in prerelease versions), and the feedback from that experience has been incorporated.

To adopt a Component Model feature into WASI, the following process should be followed:

1. While the feature is still being iterated on, WASI proposals may experiment with it only in prerelease versions (such as 0.3.0-rc-* releases) or in proposals that have not yet shipped in a stable WASI release. Stable release trains must remain implementable without the feature.

2. Once the feature’s champions and the WASI proposals that intend to use it believe the stability criteria above are met, an issue is filed on the WASI repository identifying the Component Model feature, the WASI APIs that would depend on it, and the evidence of implementation experience and incorporated feedback.

3. A vote to adopt the feature for inclusion in the next WASI release is added to a WASI Subgroup meetinggithub agenda through a pull request, just as with phase advancement votes. The SG evaluates whether the feature is genuinely stable and whether the iteration and feedback phase has been sufficient.

4. Once the SG votes to adopt the feature, stable (@since-gated) WASI APIs in the next release may depend on it. The adoption is recorded in Component Model features in WASI, and the release notes for that version must call out the newly adopted Component Model feature.

   Note: Not all Component Model features are surfaced in WASI WIT definitions. Some, such as new canonical ABI features, have no WIT-level syntax. Even in those cases, these features follow the same process.

5. From that release onward, the feature is part of the baseline set of Component Model features required to implement that WASI version, matching the feature’s status in the Component Model’s gated featuresgithub documentation (for example, WASI 0.3 adopts the features gated by 🔀 async). A PR to the Component Model repository updates that documentation to record which WASI release adopted the feature.