deprecating APIs within a WASI release family · wasi

Hey all; I just found some terminology used in wasi:http which seems to deviate from the terminology used in the specifications. By itself it's a pretty minor thing, but assuming it's something we'd want to change it leads to a much broader question: How do we want to navigate API changes within a WASI release family (e.g. WASI 0.2.x)?

Terminology: "field key" vs "field name" · Issue #107 · WebAssembly/wasi-http

Preface Hi hi, I've been working with wasi:http a fair bit recently and have been enjoying it a lot. Thank you for that! Given we're currently still in a preview and we intend to make breaking chan...

Yoshua Wuyts (Mar 11 2024 at 09:43):

At the bottom of that issue I've laid out a rough flow I think we could adopt for changes like these. Ensuring we can adopt changes as we go, but ensure we do not violate our backwards-compatibility guarantees for WASI 0.2.x either. This would depend on having some WIT-native mechanism to mark APIs as deprecated, which I'm not sure has come up before?

Yoshua Wuyts (Mar 11 2024 at 09:45):

This seems like a pretty broad issue as it comes to the evolution of our WASI worlds, and so I wanted to broach that topic with this issue as a motivating example. I'm sure this will come up more often in the future, so I figured it would be worth raising sooner. Keen to hear what folks think!

Till Schneidereit (Mar 12 2024 at 10:58):

hey Yosh! I think what you laid out there makes sense for this kind of case. For another, somewhat broader kind, I recently filed an issue for the component model about introducing support for aliases. Would be interested in hearing your take on that!

Consider adding support for identifier aliases · Issue #312 · WebAssembly/component-model

Over in #311, @oovm points out that the fact that components broadly include identifiers in their public interfaces means that it's hard to fix naming mistakes in stable APIs. I wonder if it might ...

Yoshua Wuyts (Mar 12 2024 at 12:30):

@Till Schneidereit oh yeah that makes sense to me - it sounds like having something like that could indeed be used to implement the solution for the issue I filed

Yoshua Wuyts (Mar 12 2024 at 12:31):

Do we have a sense yet for what we'd like the notation to look for this? I assume aliasing would be one use case, but generally notations might even be broader than that?

Yoshua Wuyts (Mar 12 2024 at 12:32):

(not to expand the scope further haha - but that seems like it might be the first thing missing which we'd need a solution to?)

Till Schneidereit (Mar 12 2024 at 12:43):

I agree that this would ideally want to be part of a larger annotations solution, yes. IMO it'd make sense to do something informed by existing annotations syntax—be it Rust's, TypeScripts, or whatever. I haven't really dug into the syntax design myself though

Stream: wasi

Topic: deprecating APIs within a WASI release family