Adding a note to WIT.md about WIT interface version interop & host downgrades

Open Beginner friendly
#609 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
wasm
Domain
documentation

Research direction

Start by reading WIT.md and the linked Wasmtime Linker documentation on names and semver. Add a clear note covering host-specific interface downgrades and the possibility that adding functions can break guests running against older hosts, while distinguishing this behavior from a platform requirement.

Written by the indexing model from the issue text.

Description

Hey all,

So thinking about interfaces in WIT it seems clear that there are two somewhat surprising eventualities that happen in hosts today (wasmtime, jco at the very least):

  1. Linked interfaces may be downgraded to match what is in the host (i.e. ns:pkg/iface@0.2.1 being downgraded to ns:pkg/iface@0.2.0)
  2. Partly due to (1) but in general adding functions to an existing interface (even with @since) could become a breaking change, because guests cannot predict whether hosts will have coverage or not.

This should likely be called out more clearly in WIT.md, similar to how it is called out explicitly in wasmtime's Linker documentation -- thoughts?

The ideal is to prevent people from being surprised when building components that target the newest version of a given interface but running in an older host/embedding and experiencing an unexpected runtime failure.

Downgrading is a host-specific quirk, and is technically not promised/required by a given platform (no guest can ensure that a certain platform does a certain thing with it's imports), but it is still surprising behavior that should probably be noted somewhere.

Dominant language
WebAssembly
Stars
1.4k
Forks
130
Avg merge
2d 1h
Merged PRs (30d)
15

Contributor guide

No contributing guide indexed for this repository

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.

More from WebAssembly/component-model

All issues in WebAssembly/component-model

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.