search

WebAssembly / WASI

WebAssembly System Interface
Other
4.93k stars 257 forks source link

Proposal repos: keep generating markdown? #629

Open pchickey opened 3 weeks ago

pchickey commented 3 weeks ago

The WASI subgroup maintains the wit-abi-up-to-date Github Action for checking that the wit in a proposal is valid, and that the markdown files in the proposal match the wit.

Mechanically validating the wit documents is a vital part of CI. However, keeping the rendered markdown up to date with changes in the wit creates a burden for contributors and maintainers.

In my informal survey so far, I haven't heard feedback from anyone who actually appreciates and uses the rendered markdown. I have heard feedback from numerous proposal authors and contributors that the rendered markdown creates significant inconvenience. Since the markdown is a direct transform of the wit, we could find a different way to make it available to those who use it (if they exist), e.g. by changing the action to generate markdown and publish it to github pages, or something along those lines.

I'd like to collect more feedback here, with the predisposition to stop generating markdown unless we hear from people who are really using it.

For an example of the rendered markdown, see: https://github.com/WebAssembly/wasi-filesystem/blob/main/imports.md

abrown commented 3 weeks ago

I like the idea of generating all the things automatically (Markdown, language bindings, etc.) and dumping them somewhere.

woodsmc commented 1 week ago

In my informal survey so far, I haven't heard feedback from anyone who actually appreciates and uses the rendered markdown. As someone new to a proposal or interface definition the markdown can be really very useful. The usage / reading pattern of the markdown is as follows:

  1. Understand the scope of the proposal (this may not be embedded in the wit)
  2. Understand the intended usage pattern and interface semantics (this should be in the wit)

I'm with @abrown that if it is possible to auto generate these, then all the better. It would be great to have both the scope and the usage pattern captured in one location inside the wit. - Once source of truth.

pchickey commented 1 week ago

The generated markdown has a 1:1 correspondence from the wit - only information in the wit is present in the markdown. We are not proposing to get rid of the README.md markdown, which contains additional information about the scope of proposal and etc that is not in the wit.