diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 49d1e9c33f..32b71d3cd8 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -57,5 +57,6 @@ - [Coding Guidelines](./contributing-coding-guidelines.md) - [Development Process](./contributing-development-process.md) - [Release Process](./contributing-release-process.md) + - [Implementing Wasm Proposals](./contributing-implementing-wasm-proposals.md) - [Governance](./contributing-governance.md) - [Code of Conduct](./contributing-coc.md) diff --git a/docs/contributing-implementing-wasm-proposals.md b/docs/contributing-implementing-wasm-proposals.md new file mode 100644 index 0000000000..bce9db61db --- /dev/null +++ b/docs/contributing-implementing-wasm-proposals.md @@ -0,0 +1,118 @@ +# Implementing WebAssembly Proposals + +## Adding New Support for a Wasm Proposal + +The following checkboxes enumerate the steps required to add support for a new +WebAssembly proposal to Wasmtime. They can be completed over the course of +multiple pull requests. + +* Add support to the + [`wasmparser`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmparser) + crate. + +* Add support to the + [`wat`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wat) + and + [`wast`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wast) + crates. + +* Add support to the + [`wasmprinter`](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasmprinter) + crate. + +* Add a `wasmtime::Config::enable_foo_bar` method to + the `wasmtime` crate. + +* Add a `--enable-foo-bar` command line flag to the + `wasmtime` binary. + +* Enable the spec tests in + [`build.rs`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L41-L52) + but [mark them as + ignored](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/build.rs#L196) + for now. + +* Stop ignoring individual spec tests and get them + passing one by one. + +* Enable the proposal in [the fuzz + targets](./contributing-fuzzing.html). + + * Add examples from the spec tests to [the relevant + corpora](https://github.com/bytecodealliance/wasmtime-libfuzzer-corpus). + + > The `wast2json` tool from [WABT] is useful for this. + + * Write a custom fuzz target, oracle, and/or test + case generator for fuzzing this proposal in particular. + + > For example, we wrote a [custom + > generator](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/generators/table_ops.rs), + > [oracle](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/fuzzing/src/oracles.rs#L417-L467), + > and [fuzz + > target](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/fuzz/fuzz_targets/table_ops.rs) + > for exercising `table.{get,set}` instructions and their interaction with + > GC while implementing the reference types proposal. + +* Expose the proposal's new functionality in the + `wasmtime` crate's API. + + > For example, the bulk memory operations proposal introduced a `table.copy` + > instruction, and we exposed its functionality as the `wasmtime::Table::copy` + > method. + +* Expose the proposal's new functionality in the C API. + + > This may require extensions to the standard C API, and if so, should be + > defined in + > [`wasmtime.h`](https://github.com/bytecodealliance/wasmtime/blob/c7cd70fcec3eee66c9d7b5aa6fb4580d5a802218/crates/c-api/include/wasmtime.h) + > and prefixed with `wasmtime_`. + +* Use the C API to expose the proposal's new + functionality in the other language embedding APIs: + + * [Python](https://github.com/bytecodealliance/wasmtime-py/) + + * [Go](https://github.com/bytecodealliance/wasmtime-go/) + + * [.NET](https://github.com/bytecodealliance/wasmtime-dotnet/) + +* Document support for the proposal in + `wasmtime/docs/stability-wasm-proposals-support.md`. + +## Enabling Support for a Proposal by Default + +These are the standards that must be met to enable support for a proposal by +default in Wasmtime, and can be used as a review checklist. + +* The proposal must be in phase 4, or greater, of [the + WebAssembly standardization process][phases]. + +* All spec tests must be passing in Wasmtime. + +* No open questions, design concerns, or serious known + bugs. + +* Has been fuzzed for at least a week minimum. + +* We are confident that the fuzzers are fully + exercising the proposal's functionality. + + > For example, it would *not* have been enough to simply enable reference + > types in the `compile` fuzz target to enable that proposal by + > default. Compiling a module that uses reference types but not instantiating + > it nor running any of its functions doesn't exercise any of the GC + > implementation and does not run the inline fast paths for `table` operations + > emitted by the JIT. Exercising these things was the motivation for writing + > the custom fuzz target for `table.{get,set}` instructions. + +* The proposal's functionality is exposed in the + `wasmtime` crate's API. + +* The proposal's functionality is exposed in the C API. + +* The proposal's functionality is exposed in at least + one of the other languages' APIs. + +[phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md +[WABT]: https://github.com/WebAssembly/wabt/