WebAssembly / WebAssembly/WASI

Proposal repos: keep generating markdown?

Open
#629 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

S-inactive
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.