component-docs
component-docs copied to clipboard
bytecodealliance
Registry tooling and wac
Added instructions for tools that have registry support, (cargo-component, wit, and wac). The tools that have registry support have a few different assumptions about how both WIT packages and components are referenced, so I had to change some of the existing examples a bit.
That being said I'm not sure if we want to continue to encourage users to perform composition using some of the old flows anymore (wasm-compose may end up being replaced by wac, in which case UI based composition may look a bit different?).
I figure these changes are a good starting point for a discussion about these topics, which may lead to more changes in the examples. Also opening as a draft as there are some pending code changes that will be needed in order for users to have multiple namespaces in their compositions... namely https://github.com/bytecodealliance/cargo-component/pull/275, https://github.com/bytecodealliance/wac/pull/91, https://github.com/bytecodealliance/registry/pull/263. The docs should probably not be updated until these get merged.
The relevant PRs have been merged now, so the tools should work as indicated in the proposed changes (when building from main, I don't believe new releases have occurred yet). In the SIG Docs group there was some conversation about if some of the information about wac belongs in either the wac repo docs or a wac book, so I'll try and get a clearer idea of that before asking for review.
Also... it seems this PR has some goals in common with the changes proposed here. Specifically this PR splits wit packages and publishes them to a registry. It also covers how to use example components that have been published to the registry in a composition, as well as how the user can compose their own components that they've published. Still having a think on it... but it seems that since both split up wit across multiple packages, perhaps they should do so the same way.
Removed a lot of the details covered in the README's for the tools referenced. Think this is ready for review at this point.
We talked about this a bit in the TSC meeting today, since it touches on interesting aspects for Bytecode Alliance hosted activities. What we realized is that we think that content hosted by the Bytecode Alliance should be vendor-neutral when it comes to anything directly relevant to the Bytecode Alliance's mission and principles.
We're looking into how best to document this as a general policy, but in the meantime I wanted to give a heads-up about how it impacts the content here.
Specifically, we concluded that examples and documentation shouldn't rely on workflows that are only possible with proprietary products or services in the domain the Bytecode Alliance operates in, nor should they showcase such products or services over alternatives. As such, we think the documentation and examples here shouldn't rely on the wa.dev registry, and would like to request those to be changed before this PR is merged. I want to emphasize that this isn't in any way about wa.dev specifically: the same principles would apply to documentation or examples showing how to deploy components to a proprietary hosting platform, for example.
(To give a completely unrelated historical example of a change that we discussed and agreed would also be required by this policy, if for slightly different reasons: this very project initially relied on Fermyon's Spin runtime, and Fermyon's hosting platform, but has since been changed to use GitHub Pages instead. While none of the user-visible content showed that anything proprietary was used, and while the change back then wasn't made to achieve alignment with a policy, in our discussion today we agreed that this use of Fermyon's product would not be compliant with the policy, as it would force everyone contributing to this project to use said product, giving it a preferential position. [Which wasn't the intent behind the original approach, but in hindsight would've been a result.])
We talked about this a bit in the TSC meeting today, since it touches on interesting aspects for Bytecode Alliance hosted activities. What we realized is that we think that content hosted by the Bytecode Alliance should be vendor-neutral when it comes to anything directly relevant to the Bytecode Alliance's mission and principles.
We're looking into how best to document this as a general policy, but in the meantime I wanted to give a heads-up about how it impacts the content here.
Specifically, we concluded that examples and documentation shouldn't rely on workflows that are only possible with proprietary products or services in the domain the Bytecode Alliance operates in, nor should they showcase such products or services over alternatives. As such, we think the documentation and examples here shouldn't rely on the wa.dev registry, and would like to request those to be changed before this PR is merged. I want to emphasize that this isn't in any way about wa.dev specifically: the same principles would apply to documentation or examples showing how to deploy components to a proprietary hosting platform, for example.
(To give a completely unrelated historical example of a change that we discussed and agreed would also be required by this policy, if for slightly different reasons: this very project initially relied on Fermyon's Spin runtime, and Fermyon's hosting platform, but has since been changed to use GitHub Pages instead. While none of the user-visible content showed that anything proprietary was used, and while the change back then wasn't made to achieve alignment with a policy, in our discussion today we agreed that this use of Fermyon's product would not be compliant with the policy, as it would force everyone contributing to this project to use said product, giving it a preferential position. [Which wasn't the intent behind the original approach, but in hindsight would've been a result.])
Makes sense! I'll have a go at reducing the changes to those that introduce wac and other workflows that don't reference wa.dev.