Require design rationals for proposals

[Robbepop]

We had a brief discussion about adding a requirement for rationals for WebAssembly proposals.

You can read more about the existing discussion here:
WebAssembly/reference-types#71

The motivation for this is mainly the following:

This larger road map admittedly is a bit difficult to extract from individual proposal repos. Respective discussions tend to be buried in GH issues and meeting notes, and it is of course changing constantly. We could probably do a better job at documenting it.

This is exactly why I think that design rationals could be a nice requirement for Wasm proposals. When I was reading the base Wasm spec I was having sooo many questions behind certain designs until I found the design rational docs. Really one of my most loved Wasm docs so far.

In general we already have a pretty impressive rationals design document for the general WebAssembly specification. We simply lack those for all the WebAssembly proposals in the pipeline. Since we already have the rationals design document for the generial Wasm specification we are already in need of enumerating those rationals once a proposal has been merged into the official standard. Requiring proposal authors to do this upfront will have the additional benefit of tracking the current state of design rationals of all proposals and upon merging they could simply be merged into the official Wasm spec rationals design document.

This puts a bit of work into the hands of Wasm proposal authors, lifts of work from the general Wasm spec maintainers (also they might not even know what rationals are behind the design decisions that have been made) and further improves acceleration of development through making the discussions available for a wider audience. (Nobody has time to read every single detail in a proposal to make themselves aware of all the rationals but everybody interested enough should have enough time to read through a brief design rationals document).

All in all I'd say having rationals requirements is a win for all parties.

• New people that try to get into a discussion of a proposal will have a simpler time getting into the topic.
• The general Wasm spec can simply use the provided rationals in their own required rationals docs.
• Proposal authors have a proper way to communicate the results of the accumulation of their thoughts about their proposal in a brief way which strengthens their arguments for their current design or at least makes them more understandable for others.

[binji]

Thanks for writing this up! I'll add this to the agenda for discussion in the next meeting. If you are a CG member, feel free to join the meeting to begin the discussion. Otherwise, I'm happy to bring do it.

[Robbepop]

Thanks for writing this up! I'll add this to the agenda for discussion in the next meeting. If you are a CG member, feel free to join the meeting to begin the discussion. Otherwise, I'm happy to bring do it.

As far as I am aware of I am not a member and I'd be happy if you can bring it up there. :)
Is there a way I can observe the meeting or get the information about the outcomes afterwards?

[binji]

You can join the CG here, if you like: https://www.w3.org/community/webassembly. We ask that people join the group if they'd like to attend the meetings. Otherwise, you can read the meeting notes posted afterward.

[binji]

We discussed this in the Jan 21 CG meeting. In general, folks were in favor of doing this. We discussed a bit and decided we'd try to determine how to make progress offline.

@tlively @fgmccabe @RossTate you all seemed to have opinions about how best to do this.

[RossTate]

I'm hoping to finish drafting a design-rationale document for our proposal this week. That might be a useful example of a rationale document that was developed early in the proposal process, and I'll be happy to get criticism as to how it can be improved. If y'all think such a concrete and current example might help structure the discussion, I'm happy to link to it here once it's done.

[tlively]

It would definitely be useful to get input from various current proposals about what kinds of questions are asked most frequently and what the most successful organization of information has been.

I would be in favor of collaborating on a proposal template or set of templates. I thought @binji's idea of placing these templates in the proposals repo was a good one.

[RossTate]

A preliminary draft of our design rationale can now be found in the ongoing pull request: https://github.com/soil-initiative/gc/pull/1
I propose we use the pull request only to discuss the specific rationale, and use here to discuss at a meta level whether it serves as a useful model for design-rationale documentation.