Update distributing components section with docs on wkg #220
Conversation
Signed-off-by: Kate Goldenring <[email protected]>
There was a problem hiding this comment.
A lot of comments, I'm afraid, but I think most of them boil down to looking for a bit more conceptual grounding, and perhaps some simplified guidance. I'd also find it really helpful to have the wkg commands directly compared, and to be given guidance as to when to use them (I think the answer is to use publish and get/fetch, with the oci commands being lower level, but I am not sure).
I hope the comments make sense - I'm afraid they hop back and forth a lot! Happy to elaborate as needed or try to come up with more concrete suggestions.
And thanks for taking this on - it's a ton better than the previous page, and it definitely helped me get my head around the previously vague wkg config file and the seemingly ever-evolving set of wkg commands. It's already super useful.
| A component is pulled from a OCI registry using `wkg oci pull`. The example below pulls a component from GHCR: | ||
|
|
||
| ```sh | ||
| wkg oci pull ghcr.io/user/hello:0.1.0 -o hello.wasm |
There was a problem hiding this comment.
It might be good to highlight the output e.g. "pulls a component from GHCR and saves it to hello.wasm" because I was initially thinking "huh where does it pull to"
| default_registry = "ghcr.io" | ||
|
|
||
| [namespace_registries] | ||
| wasi = { registry = "wasi", metadata = { preferredProtocol = "oci", "oci" = {registry = "ghcr.io", namespacePrefix = "webassembly/" } } } |
There was a problem hiding this comment.
I can copy this but I'm not sure I understand it. My guess is that this is talking about "packages with the wasi prefix" and saying "they should be got from the wasi registry and then... saying where the wasi registry is? It might be good to explain the config file at a high level (with a link for details) alongside the recommendation?
| default_registry = "ghcr.io" | ||
|
|
||
| [namespace_registries] | ||
| foo = { registry = "foo-registry", metadata = { preferredProtocol = "oci", "oci" = {registry = "ttl.sh", namespacePrefix = "wasm-components/" } } } |
There was a problem hiding this comment.
Is the name foo-registry significant in any way?
There was a problem hiding this comment.
it can be referenced to do package overrides in another section of the config. I didn't think it was necessary to go to that level of detail, though
kate-goldenring
force-pushed
the
wkg-docs
branch
from
3eea831 to
0c84ffb
Compare
Signed-off-by: Kate Goldenring <[email protected]>
kate-goldenring
force-pushed
the
wkg-docs
branch
from
0c84ffb to
c13a5ff
Compare
|
@itowlson this should be ready for a new review. I revamped the docs to be more comprehensive. @thomastaylor312 I'd appreciate your |
There was a problem hiding this comment.
This is great @kate-goldenring - it really clicked for me when I read through it this time. Thank you for your patience with my handwaving! I'm afraid there are still a few things, mostly nits but a few suggestions on context and structure, but all minor. Really appreciate your work on this all the same!
| The [`wasm-pkg-tools` project](https://github.com/bytecodealliance/wasm-pkg-tools) enables fetching and publishing Wasm components to OCI registries. It contains a `wkg` CLI tool that eases distributing and fetching components and WIT packages. `wkg` contains several subcommand: | ||
|
|
||
| - `wkg oci` - is a CLI wrapper around the [oci-wasm](https://github.com/bytecodealliance/rust-oci-wasm) crate which enables pushing/pulling Wasm artifacts to/from any OCI registry | ||
| - `wkg publish` - pushes *library* components or WIT packages |
There was a problem hiding this comment.
I'm not quite sure what the emphasis on "library" is aiming at. It implies that there are certain components I can't publish but it's not quite clear to me what the distinction is.
There was a problem hiding this comment.
I wanted to emphasize that wkg publish is used for publishing components that are meant to be consumed rather than executed, but i guess you could publish a component that implements wasi:cli/run.
| The [`wasm-pkg-tools` project](https://github.com/bytecodealliance/wasm-pkg-tools) enables fetching and publishing Wasm components to OCI registries. It contains a `wkg` CLI tool that eases distributing and fetching components and WIT packages. `wkg` contains several subcommand: | ||
|
|
||
| - `wkg oci` - is a CLI wrapper around the [oci-wasm](https://github.com/bytecodealliance/rust-oci-wasm) crate which enables pushing/pulling Wasm artifacts to/from any OCI registry | ||
| - `wkg publish` - pushes *library* components or WIT packages |
There was a problem hiding this comment.
Comparing to wkg oci this invites the question "pushes to where" but honestly I am not sure there is a good answer that fits in a single line! The distinction is kind of "as a CM package, addressable by package name" vs "as an OCI thing, addressable by physical location" but I'm not sure how to wrap that up. Maybe we should have another para between the intro para and the list along the lines of:
The usual way of using wkg is to address packages by their package name - for example,
example:[email protected]. When using wkg this way, you don't need to know about the physical location of the package - wkg configuration handles that for you. If you need to, though, you can also use wkg to work with OCI artifacts directly, addressing them by OCI references.
Then this line could refer back by saying e.g. "publish components or WIT packages by package name" or something.
(I'm not wedded to any particular structure or phrasing - just wanting to provide some context for this command.)
There was a problem hiding this comment.
This is a good distinction of "by package name". I incorporated your suggestions
|
|
||
| ## `wkg` Configuration Files | ||
|
|
||
| The `wkg` tool uses a configuration file to understand where to publish and fetch specific packages to and from. It provides the ability to configure: |
There was a problem hiding this comment.
Maybe provide some context along the lines of "When you use wkg, you don't interact with physical locations, only with package names." (And then hopefully the config file can be understood in terms of "mapping package naming to physical location" kind of thing.)
There was a problem hiding this comment.
Added this line about mapping package name to location. I like it!
Signed-off-by: Kate Goldenring <[email protected]>
kate-goldenring
force-pushed
the
wkg-docs
branch
from
8360fdd to
45d9c4e
Compare
|
@itowlson thank you for another round of great feedback. I believe i have incorporated your suggestions. |
|
|
||
| ## Distributing WIT and Components by Package Name with `wkg publish` | ||
|
|
||
| Once you've [configured `wkg`](#wkg-configuration-files) to know where to publish packages to, you can use the `wkg publish` command to publish *components* or *interfaces* to be consumed by others. |
There was a problem hiding this comment.
It might be worth noting that you'll need to configure credentials for pushing and show an example. Can also just link to wkg docs again if easier!
There was a problem hiding this comment.
We reference that in the configuration section briefly:
The configuration file also includes credentials for private registries, or for pushing to registries where you have permission, and other configuration options. See the [`wkg` docs for more configuration options](https://github.com/bytecodealliance/wasm-pkg-tools?tab=readme-ov-file#configuration).I think I'd prefer to leave that to the wkg documentation
closes #203