Hi @dschuff, we're looking at these and for the most part these seem reasonable, but we noted that the reference types explainer is full of questions and has a big TODO. Then we realized that most of the explainers are old and no longer being updated.

It seems like the WG work mode involves forking the spec for a feature and then archiving the fork once the changes are merged. However, this means that the explainers are sometimes not updated to include the sort of stuff the TAG likes to see, little things like user benefit (see our explainer explainer for more). Is there anywhere that we can get up-to-date information in that form? None of us are particularly expert at reading WASM specs, so it's hard to find these features, let alone find a discussion about benefits and trade-offs.

Unfortunately there isn't such a convenient document. Reference types is actually especially bad in this respect (i.e. listing the design considerations in isolation) because it was carved out of the GC proposal as a prerequisite. The explainer for GC has more background (and details in the GC MVP); the rationale was basically to pull out a very minimal subset (the concept of a reference type, as well as the externref type and the allowance for multiple tables) to go through the process first.

Thanks for pointing to the GC docs, those definitely help.

Personally, I find the need to document things like user benefit as less acute for WASM. It was worth asking though. It's a bit of a shame that the documentation created during the development of features is ultimately lost. Having a well-maintained set of that sort of documentation is expensive, so it's understandable how things end up in this state.

Yeah, we worked on documenting things like design rationale in the early days, but haven't really kept it up with every proposal as we've added them. User benefit is of course different (as wasm would be mostly transparent to end users) but every proposal has to consider e.g. developer benefit as it goes through the phases. Usually when champions request phase advancement they make a presentation that covers the design and often includes use cases and benefit (especially in early stages) design rationale, notable changes, etc. Those are all posted publicly, so at bare minimum it would be pretty straightforward to collect those, with links to the meeting notes, somewhere more convenient. Maybe we could have champions do that when they advance to phase 4.

Hi and thank you for your response, @dschuff. We reviewed again today and we agree that making those design rationale docs more discoverable, as you suggested, would be a good idea. Other than that we are satisfied with the proposal. Thanks for allowing us to review.

Thank you!