Add docs on when to add new cargo features

docs/contributing-architecture.md

@@ -78,6 +78,14 @@ In `crates/javy/src/runtime.rs`:
 
 Read the `config` and call the appropriate methods on `context` to apply the configuration.
 
+#### When to add a Cargo feature
+
+You should gate your feature by a Cargo feature if:
+
+- Your feature requires additional dependencies that would not otherwise be required.
+- Your feature would otherwise increase the size of the produced Wasm module.
+- Your feature requires enabling additional features in the `quickjs-wasm-rs` crate.
+
 ### `javy-apis`
 
 Common JS APIs for use with a `javy::Runtime`. For example, `console`, `TextEncoder`, `TextDecoder`. If there is a standard JS API that seems like it would be useful to multiple users of Javy, it should be implemented in this crate. If this is an API specific to your use case, you should define it in a crate of your own and register the implementation using a similar approach to how the APIs in this crate define their implementations.
@@ -267,22 +275,49 @@ and
       random::Random.register(runtime, &config)?;
 ```
 
+#### When to add a cargo feature
+
+All new APIs should be gated by a cargo feature so users of the crate can opt into including them in their runtime.
+
 ### `javy-cli`
 
 The CLI for compiling JS to Wasm. This isn't intended to be a CLI that accommodates all uses for all users but rather to provide a useful base of functionality. This is kind of similar to how Wasmtime ships with a crate and a CLI and doing non-generic things with Wasmtime requires writing your own CLI around the Wasmtime crate.
 
+#### When to add a cargo feature
+
+You should gate your feature with a cargo feature if:
+
+- It's not commonly going to be used and it would complicate the CLI options to include enabling it. For example, printing the WAT of a dynamic module is not something users would want 99.9% of the time and including it as an option on the CLI would make the `--help` output harder for most users to understand.
+- You want to have integration tests in the `javy-cli` crate that should only run when the `javy-core` crate is built with a non-default configuration (that is, with different cargo features enabled). For example, we introduced the `experimental_event_loop` cargo feature in the `javy-cli` crate since we test for different expected outputs when using a promise when the `experimental_event_loop` cargo feature is enabled on the `javy_core` crate compared to when that cargo feature is disabled.
+
 ### `javy-core`
 
 Gets compiled to `javy_core.wasm` and `javy_quickjs_provider.wasm` for use by the CLI and in environments for running dynamically linked modules. This isn't intended to be used as a code library by third parties. Contains logic for driving the `javy` crate for Wasm modules generated by `javy-cli`.
 
+#### When to add a cargo feature
+
+You should gate your feature with a cargo feature if:
+
+- You want to support building a Wasm module with an experimental configuration of the runtime. We do this for the event loop because the current implementation has not been thoroughly vetted. We also need a build of Javy with event loop support to run a number of web platform tests for text encoding.
+
 ### `quickjs-wasm-rs`
 
 Provides an ergonomic API around the `quickjs-wasm-sys` crate as well as a `serde` implementations for `JSValueRef`.
 
+#### When to add a cargo feature
+
+You should gate your feature with a cargo feature if:
+
+- Including your feature will materially increase the size of the produced Wasm module.
+
 ### `quickjs-wasm-sys`
 
 A Rust wrapper around the QuickJS C library.
 
+#### When to add a cargo feature
+
+We do not anticipate changes to this library requiring a new cargo feature. Please reach out on Zulip or in GitHub if there is a reason to add a new cargo feature.
+
 ## NPM packages
 
 ### `javy`