Support `@deprecated` gates in WIT

[yoshuawuyts]

Motivation

Following up on the conversation in https://github.com/WebAssembly/wasi-http/issues/107 (renaming field-key to field-name), we should support some form of @deprecated notation to mark individual items as deprecated. In the linked issue I proposed the following flow for that:

Navigating deprecations within a WASI release family

If we assume for a second this is a change we want to make, that opens up the question of how we would want to navigate a change like this. WASI 0.2 was just ratified, and WASI 0.3 is likely still a while out. And if we were to implement for example #94 (add a fields.keys method), we'd be doubling-down on the existing terminology instead of the terminology we would prefer.

This is a question which is generally broader than this issue, but I think it would be good if we could establish a process for making changes like these within a minor WASI version. An example flow I'm thinking of is:

1. Introduce a new alias type field-name = field-key (or alias it directly to string if that's legal in our projections).
2. Change all APIs which take field-key to take a field-name instead.
3. Mark field-key as deprecated for WASI 0.2.
4. When we release WASI 0.3 we remove field-key from the API surface.

If we were able to do something like this we could release the changes as part of a WASI 0.2.x release without breaking any existing code. And then in a WASI 0.3.0 release we could finalize the changes by actually removing deprecated APIs. I don't know whether we already have a way to support deprecating APIs in WIT; but if we don't that may be a good thing to consider adding.

Feature design

Just like @since and @unstable, it would make sense to add a third gate: @deprecated. I think it would make sense for this feature to also carry a version = field (just like @since) to mark when in which version it was deprecated. As well as some way to provide a message why this API was deprecated. I'm suggesting we use the message = field name for that.

This matches Rust's approach fairly closely, which has a #[deprecated(since="", note="")] notation. Swift is a little fancier, and has an @available notation which supports a number of configurations. What we're proposing here would in Swift be written as @available(*, deprecated, message: ""). Swift also supports a rename field which exists specifically to point to other symbols. But unless we have an existing path notation for it, I'm hesitant to propose we add it straight away.

Put together I'm proposing we should change WIT's feature gate notation to the following:

gate ::= unstable-gate
       | since-gate
       | deprecated-gate

unstable-gate ::= '@unstable' '(' feature-field ')'
since-gate ::= '@since' '(' version-field ( ',' feature-field )? ')'
deprecated-gate ::= '@deprecated' '(' version-field ( ',' message-field )? ')'

feature-field ::= 'feature' '=' id
version-field ::= 'version' '=' <valid semver>
message-field ::= 'message' '=' message

cc/ @lukewagner I'd be keen to get your thoughts on this - anything this might be missing, or you think we should do differently?

[lukewagner]

That all makes sense to me and seems like a useful addition to the overall semver workflow we started with @since and @unstable.

One question: it seems like, to get the full effect, we'd want wit-bindgen to be able to add whatever "deprecated" annotation to the generated function signatures which suggests that wit-bindgen would need access to the custom section into which these gates are encoded. Just to confirm, does wit-bindgen already have this on hand or would it make sense to plumb it in? It seems like we'd also need custom sections for doc-comments, so I'd assume 'yes', but I thought I'd check.

[yoshuawuyts]

We should indeed already support this. I remember checking with Alex on this a while back and he explained that it was already possible to round-trip WIT files with gates on them when encoding them to Wasm and back. Though I haven't tested this myself yet.