Document custom sections for OCI-compatible annotations

[yoshuawuyts]

Closes #230. This documents custom sections that correspond to the OpenContainer Annotations specification, enabling build tools to encode metadata that is picked up by publishing tools, and translated to a format that registries can understand. This functionality is currently supported by wasm-tools, wasm-pkg-tools, and an open PR implementing this for cargo-component is currently out for review. Thanks!

References

• #230
• https://github.com/bytecodealliance/wasm-tools/issues/1922
• https://github.com/bytecodealliance/wasm-pkg-tools/pull/146
• https://github.com/bytecodealliance/cargo-component/pull/372

[dschuff]

These section names are very generic, but they seem to have very specific meaning wrt OCI. It's easy to imagine some tool that's unaware of OCI using one of them. I think it would make sense to give them some common prefix (e.g. oci.author). Maybe this isn't feasible given that there's already existing tooling, but it seems worth at least considering.

[yoshuawuyts]

Thanks for raising this @dschuff - we did consider this point in discussion within the BA Packaging SG. Though I'm not a member of that group, we did collaborate on this and discussed this a fair bit.

You're quite right these names are quite generic, but the encoding formats themselves are very generic too. Most fields annotation formats are either free-form strings or valid URLs. The only other formats are RFC3339-formatted timestamps, and SPDX-encoded timestamps. I think both formats that are about as close to universal standards for their respective data-types as you can reasonably get. If a tooling vendor decides to start adding some metadata to their Wasm binaries without consulting tool-conventions first, it seems more likely than not that it will just be compatible.

Another reason not to prefix this is that the metadata is not just OCI-specific either. Take for example the description annotation. When working with components, only the description of the root component would be used to populate the OCI package fields. But when inspecting a component there is often a mix of modules and components contained within (e.g. see https://github.com/bytecodealliance/wasm-tools/pull/2079). Adding descriptions, versions, and source info to each of these would be useful for people to better understand what their components are made up of!