Explain webgpu breaking-change freeze in documentation (emscripten-co…

…re#22481)

Suggested in
emscripten-core#21552 (comment)

src/library_webgpu.js

@@ -7,9 +7,15 @@
 /*
  * WebGPU support.
  *
- * This file implements the common C header <webgpu/webgpu.h> on top of the
+ * IMPORTANT NOTICE:
+ * These bindings are in a temporary **breaking-change freeze**.
+ * Bugfixes and small feature additions are still welcome.
+ * Please see system/include/webgpu/README.md for more information.
+ *
+ * This file and system/lib/webgpu/webgpu.cpp together implement the
+ * to-be-standardized C header <webgpu/webgpu.h> on top of the
  * browser's native JS WebGPU implementation. This allows applications targeting
- * wgpu-native (https://github.com/gfx-rs/wgpu) or
+ * wgpu-native (https://github.com/gfx-rs/wgpu-native) or
  * Dawn (https://dawn.googlesource.com/dawn/) to also target the Web with the
  * same graphics API and fairly minimal changes - similar to OpenGL ES 2.0/3.0
  * on WebGL 1.0/2.0.

system/include/webgpu/README.md

@@ -1,3 +1,17 @@
+## Important Notice
+
+Emscripten's WebGPU bindings are in a temporary **breaking-change freeze**.
+Bugfixes and small feature additions are still welcome.
+
+Stable headers are being developed in [webgpu-headers](https://github.com/webgpu-native/webgpu-headers)
+but will require a number of breaking changes relative to Emscripten's current implementation.
+Instead of constantly landing incremental breaking changes in Emscripten, the Dawn project
+(native C++ implementation of webgpu.h) has forked Emscripten's bindings to do these incremental
+changes, before upstreaming all of the changes at once back into Emscripten.
+See [emdawnwebgpu](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/emdawnwebgpu/) for more info.
+
+# WebGPU Bindings
+
 These files, and several snippets of other files, are generated by Dawn
 (Chromium's WebGPU library):
 - [Generator](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/generator/)
@@ -14,9 +28,11 @@ better compatibility with Dawn: it has roughly the same API as Dawn's copy, but
 is included here because it is strongly tied to an exact `webgpu.h` revision.
 
 To update these bindings from Dawn:
+(TODO: these links are broken because Chromium Code Search is not currently building these generated files.)
+
 1. Copy [`webgpu_enum_class_bitmasks.h`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/dawn/include/webgpu/webgpu_enum_class_bitmasks.h) from Dawn's source to `system/include/webgpu/webgpu_enum_class_bitmasks.h`
 1. Build Dawn's `emdawnwebgpu_headers_gen` and `emdawnwebgpu_js_gen` targets (in a gn build of Dawn, or a build of Chromium) - or, use the Chromium Code Search copy of the generated files if no changes are needed
-1. Copy the generated [`include`](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/src/emdawnwebgpu/include/) files into Emscripten's `system` directory
+1. Copy the generated [`include`](https://source.chromium.org/chromium/chromium/src/+/main:out/linux-Debug/gen/third_party/dawn/src/emdawnwebgpu/include/) files into Emscripten's `system` directory:
     - `system/include/webgpu/webgpu.h`
     - `system/include/webgpu/webgpu_cpp.h`
     - `system/include/webgpu/webgpu_cpp_chained_struct.h`

system/lib/webgpu/README.md

@@ -1,2 +1,2 @@
-This files is generated by Dawn (Chromium's WebGPU library).
+These files are generated by Dawn (Chromium's WebGPU library).
 See [`system/include/webgpu/`](../../include/webgpu/) for info.