# WASI development process

## WASI uses a 3-phase process:

- [`ephemeral`](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`](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`](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.

[the CG's phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md