WASI development process

WASI uses a 3-phase process:

• ephemeral: The development staging area. New API proposals API-changing fixes to existing APIs should be submitted as Pull Requests making changes to this directory. This directory provides no API stability or versioning. APIs in this directory use API module names starting with wasi_ephemeral_.

• snapshot: Usable APIs. APIs in ephemeral will be occasionally snapshotted and promoted into snapshot, with approval from the Subgroup, considering the overall suitability of the APIs themselves, their documentation, test coverage, and availability of polyfills when appropriate. Once merged, the API modules will be considered stable, though they may be superseded by newer versions. Proposals to promote specific APIs should be submitted as Pull Requests that:

  1. git mv contents of phases/snapshot/ to phases/old/snapshot_{old_snapshot_number}.
  2. cp -R contents of phases/ephemeral/ into phases/snapshot/.
  3. Rename files copied into phases/snapshot/ to substitute ephemeral for snapshot in file names. Append the new snapshot number to each name.
  4. Update module names given in .witx files according to the previous step.
  5. Update tests in tools/witx/tests/wasi.rs to point at new snapshot, and add a test pointing at the just-archived snapshot under old.
  6. Optionally, under `phases/old/snapshot_{old_snapshot_number}, add polyfills for superceded APIs using the new APIs.

  Pull Requests may also add additional tests, documentation, or polyfills for existing snapshot APIs.

• old: When APIs in snapshot spec are replaced by new versions, the old API modules are moved to the old directory. When possible, old APIs may be accompanied by polyfill modules which implement their API in terms of newer versions of the API.

Rationale

Relationship to the CG's phases

When WASI becomes more mature, such that we have an established base and we're adding incremental functionality to it, we may want to adopt a process like the CG's phases. However, right now, everything in WASI is undergoing changes, so we have a greater need to iterate with flexibility.

Relationship to standards

WASI should eventually become a standard at the level of WebAssembly itself. Right now, it needs a lot of work before it's ready. The snapshot tree is meant to serve a practical purpose for people who want to work with APIs today, with the understanding that everything is still evolving. It's not meant as a replacement for proper standardization, which will happen once the overall API is more mature.