WebAssembly / WebAssembly/WASI
Proposal repos: keep generating markdown?
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 5.8k
- Forks
- 333
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 3
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the wit-abi-up-to-date GitHub Action and the wasi-filesystem imports.md example linked in the issue. Read the existing feedback, then determine whether contributors use the rendered markdown and whether it should continue being generated or be published another way. Done looks like a documented project decision with an agreed direction.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, wasm
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100