Help users draw the rest of the owl
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- wasm
- Domain
- documentation
Research direction
Start with the WAC README and language guide, then compare their composition guidance with the linked component model book chapter. Done would be an agreed learning guide or cookbook that explains interface-focused composition, common patterns, constructs, concepts, and motivating examples for intermediate users.
Written by the indexing model from the issue text.
Description
WAC has a handy readme which shows plugging a function export into a function import. For more complex compositions, it directs you to the language guide. Unfortunately, I'm afraid I found the language guide overwhelming, and struggled to see how to map it onto even simple use cases. (My use case at hand was "I want to plug two interfaces together, rather than two functions.")
There is some coverage in the component model book (https://component-model.bytecodealliance.org/composing-and-distributing/composing.html), so I am not sure if it would be better to build that out, or to reorganise the repo docs into a learning guide/cookbook vs advanced reference. But it would be great to have something to cover that intermediate ground and to help users get more comfortable with WAC.
I would suggest a learning guide/cookbook would:
- De-emphasise the "superset of WIT" and evaluation order stuff
- Focus on interfaces (not necessarily to the exclusion of functions, but as the default starting point)
- Focus on common patterns (plug, adapter, middleware chain, fan-out, ...?)
- Guide the reader's intuition by using meaningful names (e.g. "oauth:authenticate" or "regex:expression" or "print" rather than
a,bandi) - Explain when you would use constructs (e.g. when would I use
import?) - Explain the differences between constructs (import is "to import an instance", but new "instantiates a component and returns a component instance" - so which do I use?)
- Explain concepts (there are instances, are these like running instances?)
- Motivate expressions by usage (e.g. show a real usage of spread, when would I want "postfix access" vs "postfix named access")
I'm happy to help with this, although because of the aforementioned overwhelming and struggling I don't yet feel confident to figure most of it out myself! But I'd be happy to work with the WAC devs on something if you're open to it!
cc @kate-goldenring @vados-cosmonic for documentation SIG input and thoughts
- Dominant language
- Rust
- Stars
- 207
- Forks
- 41
- Avg merge
- 4d 9m
- Merged PRs (30d)
- 4
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
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.
More from bytecodealliance/wac
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
bytecodealliance/wac#219 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 25/100
bytecodealliance/wac#170 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 30/100
bytecodealliance/wac#169 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 30/100
bytecodealliance/wac#166 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 45/100
bytecodealliance/wac#165 ·
All issues in bytecodealliance/wac
Similar issues
-
security-scan
Difficulty 1/5 Under an hour Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
content good first issue
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
StudentSuite/awesome-skills-plugins-for-students#293 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
gfx-rs/wgpu-native#636 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
maintainer-needed p2 remote triaged
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day