Add a README section about p1-vs-p2 (#74)

README.md

@@ -83,6 +83,51 @@ Hello, world!
 
 [Wasmtime]: https://github.com/bytecodealliance/wasmtime
 
+# WASIp2 vs WASIp1
+
+In January 2024 the WASI subgroup published WASI 0.2.0, colloquially known as
+"WASIp2". Around the same time the subgroup additionally decided to name the
+previous iteration of WASI as "WASIp1", historically known as "WASI preview1".
+This now-historical snapshot of WASI was defined with an entirely different set
+of primitives and worked very differently. This crate now targets WASIp2 and no
+longer targets WASIp1.
+
+## Support for WASIp1
+
+The last version of the `wasi` crate to support WASIp1 was the
+[0.11.0+wasi-snapshot-preview1
+version](https://crates.io/crates/wasi/0.11.0+wasi-snapshot-preview1). This
+version of the crate supported all WASIp1 APIs. WASIp1 was historically defined
+with `*.witx` files and used a bindings generator called `witx-bindgen`.
+
+## Should I use WASIp1 or WASIp2?
+
+This is a bit of a nuanced question/answer but the short answer is to probably
+use the 0.11.0 release of `wasi` for now if you're unsure.
+
+The longer-form answer of this is that it depends on the Rust targets that you
+want to support. Rust WebAssembly targets include:
+
+* `wasm32-unknown-unknown` - do not use this crate because this target indicates
+  that WASI is not desired.
+* `wasm32-wasi` or `wasm32-wasip1` - this target has been present in Rust for
+  quite some time and is recently being renamed from `wasm32-wasi` to
+  `wasm32-wasip1`. The two targets have the same definition, it's just the name
+  that's changing. For this target you probably want the 0.11.0 track of this
+  crate.
+* `wasm32-wasip2` - this target is a recent addition to rustc (as of the time of
+  this writing it's not merged yet into rustc). This is what the 0.12.0 version
+  of the crate is intended for.
+
+Note that if you use `wasm32-wasi` or `wasm32-wasip1` it's not necessarily
+guaranteed you want 0.11.0 of this crate. If your users are producing components
+then you probably want 0.12.0 instead. If you don't know what your users are
+producing then you should probably stick with 0.11.0.
+
+Long story short, it's a bit complicated. We're in a transition period from
+WASIp1 to WASIp2 and things aren't going to be perfect every step of the way, so
+understanding is appreciated!
+
 # Development
 
 The bulk of the `wasi` crate is generated by the [`wit-bindgen`] tool. The