WebAssembly / WebAssembly/WASI

Consider ways to make WIT files more discoverable

Open
#934 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
5.8k
Forks
333
Avg merge
2d 13h
Merged PRs (30d)
3

Description

I got a bit of feedback from someone who wanted to jump in and check out the wasi:http@0.3.0 WITs that they weren't easy to find. I think perhaps the following tweaks would have helped them, but happy to discuss alternatives:

  1. Inside each specifications/R release directory, add a wit subdirectory that contains a subdirectory for each proposal X that contains a copy of the WIT files from proposals/X/wit for that release (so, e.g., there'd be a specifications/wasi-0.3.0/wit/http/types.wit).
  2. Update the existing per-proposal specifications/R/X/Overview.md files to say "if you want to see the most-recent draft state of this proposal, see [proposals/X] (link)" so that it's easy to hop from a versioned snapshot to the live draft.
  3. Add links in the README.mds of all the existing archived wasi-X proposal repos to a corresponding versioned snapshot in specifications/R/X and the live draft in proposals/X (since these archived repos still tend to show up in docs and search results).

I know that this introduces some duplication within the repo, but if we never allow mutation of WIT files in specifications (only the initial copy), maybe it's ok? Happy to discuss.

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 existing specifications/R release directories, per-proposal Overview.md files, proposals/X/wit contents, and README.md files in archived wasi-X proposal repositories. First compare the current snapshot and draft layouts, then confirm the intended release/proposal mappings. Done means the proposed WIT copies and navigation links are consistently present without mutating files under specifications.

Written by the indexing model from the issue text.

Assessment

Tech stack
wasm
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.