From c41fe68af0c54406f0cd5ac457453f7a11f67691 Mon Sep 17 00:00:00 2001 From: Yosh Date: Sat, 13 Jul 2024 01:57:49 +0200 Subject: [PATCH 1/7] Add support for `@deprecated` gates to WIT --- design/mvp/WIT.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index a4006f7c..eae9c9aa 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -923,8 +923,9 @@ package-items ::= toplevel-use-item | interface-item | world-item ### Feature Gates Various WIT items can be "gated", to reflect the fact that the item is part of -an unstable feature or that the item was added as part of a minor version -update and shouldn't be used when targeting an earlier minor version. +an unstable feature, that the item was added as part of a minor version +update and shouldn't be used when targeting an earlier minor version, or that a +feature has been deprecated and should no longer be used. For example, the following interface has 4 items, 3 of which are gated: ```wit @@ -939,6 +940,9 @@ interface foo { @unstable(feature = fancier-foo) d: func(); + + @deprecated(version = 0.2.1) + e: func(); } ``` The `@since` gate indicates that `b` and `c` were added as part of the `0.2.1` @@ -953,6 +957,12 @@ change type or be removed at any time. An important expectation set by the `@unstable` gate is that toolchains will not expose `@unstable` features by default unless explicitly opted-into by the developer. +Finally, the `@deprecated` gate on `e` indicates that `e` should no longer be +used starting version `0.2.1`. `@deprecated` gates can carry an optional +"message" field which can be used to elaborate why the feature should no longer +be used and which feature to use instead. Both toolchains and host runtimes may +warn users if they detect an `@deprecated` API is being used. + Together, these gates support a development flow in which new features start with an `@unstable` gate while the details are still being hashed out. Then, once the feature is stable (and, in a WASI context, voted upon), the @@ -970,9 +980,15 @@ Specifically, the syntax for feature gates is: ```wit 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 -since-gate ::= '@since' '(' 'version' '=' ( ',' feature-field )? ')' +version-field ::= 'version' '=' +message-field ::= 'message' '=' message ``` As part of WIT validation, any item that refers to another gated item must also From 7fa46cbf7701457748b2745e3b0d6fde26b506eb Mon Sep 17 00:00:00 2001 From: Yosh Date: Wed, 17 Jul 2024 02:11:27 +0200 Subject: [PATCH 2/7] Link to core wasm string value Co-Authored-By: Luke Wagner --- design/mvp/WIT.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index eae9c9aa..d4030e64 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -988,9 +988,12 @@ deprecated-gate ::= '@deprecated' '(' version-field ( ',' message-field )? ')' feature-field ::= 'feature' '=' id version-field ::= 'version' '=' -message-field ::= 'message' '=' message +message-field ::= 'message' '=' ``` +In this syntax `` refers to core Wasm's [string +value](https://webassembly.github.io/spec/core/text/values.html#text-string). + As part of WIT validation, any item that refers to another gated item must also be compatibly gated. For example, this is an error: ```wit From 7ba35c59748be8ca9194ee59b9dd91d84ca2c7d8 Mon Sep 17 00:00:00 2001 From: Yosh Date: Fri, 19 Jul 2024 22:24:39 +0200 Subject: [PATCH 3/7] Update WIT.md Co-authored-by: Luke Wagner --- design/mvp/WIT.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index d4030e64..747fe63a 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -978,9 +978,10 @@ enable the feature by default. Specifically, the syntax for feature gates is: ```wit -gate ::= unstable-gate - | since-gate - | deprecated-gate +gate ::= gate-item* +gate-item ::= unstable-gate + | since-gate + | deprecated-gate unstable-gate ::= '@unstable' '(' feature-field ')' since-gate ::= '@since' '(' version-field ( ',' feature-field )? ')' From 51f480c32b075855951430a349843b55cf8929b9 Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 23 Jul 2024 19:02:13 +0200 Subject: [PATCH 4/7] Remove `message` field from `@deprecated` --- design/mvp/WIT.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index 747fe63a..03295c9b 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -958,10 +958,10 @@ change type or be removed at any time. An important expectation set by the default unless explicitly opted-into by the developer. Finally, the `@deprecated` gate on `e` indicates that `e` should no longer be -used starting version `0.2.1`. `@deprecated` gates can carry an optional -"message" field which can be used to elaborate why the feature should no longer -be used and which feature to use instead. Both toolchains and host runtimes may -warn users if they detect an `@deprecated` API is being used. +used starting version `0.2.1`. Both toolchains and host runtimes may +warn users if they detect an `@deprecated` API is being used. An `@deprecated` +gate is required to always be paired up with an `@since` gate. It is +semantically invalid to use `@deprecated` without also using `@since`. Together, these gates support a development flow in which new features start with an `@unstable` gate while the details are still being hashed out. Then, @@ -985,7 +985,7 @@ gate-item ::= unstable-gate unstable-gate ::= '@unstable' '(' feature-field ')' since-gate ::= '@since' '(' version-field ( ',' feature-field )? ')' -deprecated-gate ::= '@deprecated' '(' version-field ( ',' message-field )? ')' +deprecated-gate ::= '@deprecated' '(' version-field ')' feature-field ::= 'feature' '=' id version-field ::= 'version' '=' From d95c5bcdd7cb0b03dec0f959150ed353d2ae79b2 Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 23 Jul 2024 19:11:39 +0200 Subject: [PATCH 5/7] fix wording on `@deprecated` --- design/mvp/WIT.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index 03295c9b..5316613d 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -958,10 +958,9 @@ change type or be removed at any time. An important expectation set by the default unless explicitly opted-into by the developer. Finally, the `@deprecated` gate on `e` indicates that `e` should no longer be -used starting version `0.2.1`. Both toolchains and host runtimes may -warn users if they detect an `@deprecated` API is being used. An `@deprecated` -gate is required to always be paired up with an `@since` gate. It is -semantically invalid to use `@deprecated` without also using `@since`. +used starting version `0.2.1`. Both toolchains and host runtimes may warn users +if they detect an `@deprecated` API is being used. An `@deprecated` gate is +required to always be paired up with either a `@since` or `@deprecated` gate. Together, these gates support a development flow in which new features start with an `@unstable` gate while the details are still being hashed out. Then, From 9b6b70c9a942674bb20164ee0f64de63b468650d Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 23 Jul 2024 19:12:35 +0200 Subject: [PATCH 6/7] remove mention of string --- design/mvp/WIT.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index 5316613d..73ff583f 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -988,12 +988,8 @@ deprecated-gate ::= '@deprecated' '(' version-field ')' feature-field ::= 'feature' '=' id version-field ::= 'version' '=' -message-field ::= 'message' '=' ``` -In this syntax `` refers to core Wasm's [string -value](https://webassembly.github.io/spec/core/text/values.html#text-string). - As part of WIT validation, any item that refers to another gated item must also be compatibly gated. For example, this is an error: ```wit From 75d3a0f1ed77e5633be964a17d311130d358ffb9 Mon Sep 17 00:00:00 2001 From: Yosh Date: Thu, 25 Jul 2024 15:08:42 +0200 Subject: [PATCH 7/7] Add feedback from review Co-Authored-By: Alex Crichton --- design/mvp/WIT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/design/mvp/WIT.md b/design/mvp/WIT.md index 73ff583f..fbbc469f 100644 --- a/design/mvp/WIT.md +++ b/design/mvp/WIT.md @@ -941,7 +941,8 @@ interface foo { @unstable(feature = fancier-foo) d: func(); - @deprecated(version = 0.2.1) + @since(version = 0.2.0) + @deprecated(version = 0.2.2) e: func(); } ``` @@ -958,7 +959,7 @@ change type or be removed at any time. An important expectation set by the default unless explicitly opted-into by the developer. Finally, the `@deprecated` gate on `e` indicates that `e` should no longer be -used starting version `0.2.1`. Both toolchains and host runtimes may warn users +used starting version `0.2.2`. Both toolchains and host runtimes may warn users if they detect an `@deprecated` API is being used. An `@deprecated` gate is required to always be paired up with either a `@since` or `@deprecated` gate.