Create a phased structure for API development

README.md

@@ -22,3 +22,5 @@ discussions.
 
 Schedules and agendas for video conference and in-person meetings are posted
 [here](meetings/README.md).
+
+API specification proposals are [here](phases/README.md).

phases/README.md

@@ -0,0 +1,53 @@
+# 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_`.
+
+- [`unstable`](unstable): Usable APIs. APIs in `ephemeral` will be
+  occasionally snapshotted and promoted into `unstable`, 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:
+   - Move any superseded files out of `unstable` into `old`.
+   - Optionally add polyfills for superseded APIs using `unstable` APIs.
+   - Move all files supporting the APIs out of `ephemeral into `unstable`.
+   - Rename the API modules from `wasi_ephemeral_` to `wasi_unstable_`
+     and append a version number.
+
+  Pull Requests may also add additional tests, documentation, or
+  polyfills for existing `unstable` APIs.
+
+- [`old`](old): When APIs in `current` 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
+`unstable` 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

design/WASI-core.md → phases/ephemeral/docs/wasi_ephemeral_preview.md

@@ -34,30 +34,34 @@ This file is automatically generated. Do not edit.
 Source: https://github.com/NuxiNL/cloudabi
 -->
 
-# WASI Core API
+# The WASI Preview API
 
-This is the API-level documentation for WASI Core. The function names
+This is the API-level documentation for WASI Preview. The function names
 are prefixed with "\_\_wasi\_" to reflect how they are spelled in
 flat-namespace contexts, however at the wasm module level, they are
-unprefixed, because they're inside a module namespace (currently
-"wasi\_unstable").
+unprefixed, because they're inside a module namespace.
 
 Functions that start with `__wasi_fd_` operate on file descriptors,
 while functions that start with `__wasi_path_` operate on filesystem
 paths, which are relative to directory file descriptors.
 
 Much inspiration and content here is derived from [CloudABI] and [POSIX],
 though there are also several differences from CloudABI and POSIX. For
-example, WASI Core has no concept of processes in the traditional Unix
+example, WASI Preview has no concept of processes in the traditional Unix
 sense. While wasm linear memories have some of the aspects of processes,
 and it's possible to *emulate* the full semantics of processes on top of
 them, this can sometimes be unnatural and inefficient. The goal for
-WASI Core is to be a WebAssembly-native API that exposes APIs that fit
+WASI Preview is to be a WebAssembly-native API that exposes APIs that fit
 well into the underlying WebAssembly platform, rather than to directly
 emulate other platforms.
 
 This is also a work in progress, and the API here is still evolving.
 
+Historical note: this API was originally named "WASI Core", and used the
+API module name "wasi\_unstable". We've since sought to deemphasize the
+"Core" name, as the goal is to split this API up into independent
+modules so that embedders need not implement all of it.
+
 [CloudABI]: https://github.com/NuxiNL/cloudabi
 [POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/
 

design/wasi_unstable/typenames.witx → phases/ephemeral/witx/typenames.witx

@@ -1,4 +1,4 @@
-;; Type names used by the wasi_unstable module type.
+;; Type names used by low-level WASI interfaces.
 ;;
 ;; Some content here is derived from [CloudABI](https://github.com/NuxiNL/cloudabi).
 ;;