From d695c0abf4c7a2f543612df433db9793f1a38710 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 12:49:45 +0800 Subject: [PATCH 01/14] Create 0000-deprecated-scheduled-removal.md --- 0000-deprecated-scheduled-removal.md | 103 +++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 0000-deprecated-scheduled-removal.md diff --git a/0000-deprecated-scheduled-removal.md b/0000-deprecated-scheduled-removal.md new file mode 100644 index 00000000000..2e5a354ae6c --- /dev/null +++ b/0000-deprecated-scheduled-removal.md @@ -0,0 +1,103 @@ +- Feature Name: `deprecated_scheduled_removal` +- Start Date: 2023-08-13 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +This RFC proposes the addition of a `scheduled_removal` paramter to the `deprecated` attribute, to allow library authors to specify when a +deprecated item is scheduled to be removed. + +# Motivation +[motivation]: #motivation + +Currently, library authors can specify when an item is deprecated via the `since` parameter. However, when these deprecated items are removed, +it is often confusing to some library users as to why a portion of the public API is removed, without noticing that it has been already deprecated. +Users may not be aware that certain items have become deprecated, but even if they notice, they may not migrate to something else immediately. +When the deprecated items do get removed, it is then difficult for users to migrate to another API. Removal of APIs can be sudden, and users are +usually not prepared for sudden removal of deprecated items. + +Having a `scheduled_removal` attribute, that specifies the version of which a deprecated item is removed would mean users obtain the information +of when the deprecated item will be removed from the public API and hence can prepare or complete for the migration beforehand. + + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example: +```rust +#[deprecated(since = "0.2.1", scheduled_removal = "0.3.0")] +struct ThisItemIsDeprecated; +``` +Usages of this struct would result in the following warning: +``` +warning: use of deprecated unit struct `ThisItemIsDeprecated` + --> src/main.rs:5:17 + | +5 | let _ = ThisItemIsDeprecated; + | ^^^^^^^^^^^^^^^^^^^^ + | + = note: this deprecated item will be removed in version 0.3.0 + = note: `#[warn(deprecated)]` on by default +``` +The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version +`0.3.0` and would make it clear that the user needs to migrate to another API before `0.3.0` lands, otherwise their code would break and fail +to compile due to the removal of the API. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +# Drawbacks +[drawbacks]: #drawbacks + +- More work for library authors to utilise this parameter for enhanced user experience of the users. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +## A separate `scheduled_for_removal` attribute + +A separate attribute named `scheduled_for_removal` will be introduced. Usage of this attribute looks like: +```rust +#[deprecated(since = "0.2.1")] +#[scheduled_for_removal(at = "0.3.0")] +struct ThisItemIsDeprecated; +``` +Which would generate the following warning: +``` +warning: use of unit struct `ThisItemIsDeprecated` that is scheduled for removal + --> src/main.rs:5:17 + | +5 | let _ = ThisItemIsDeprecated; + | ^^^^^^^^^^^^^^^^^^^^ + | + = note: this item will be removed in version 0.3.0 + = note: `#[warn(scheduled_for_removal)]` on by default +``` +The `scheduled_for_removal` lint would be introduced alongside with this attribute. + +This was briefly considered but ultimately personally vetoed because another attribute is quite some work, and it is like an extension to the `deprecated` +attribute - describing when will this item will be removed. Hence, adding the `scheduled_removal` parameter is preferred hence this proposal is based +on a new parameter rather than a new attribute. + +# Prior art +[prior-art]: #prior-art + +- The [JetBrains Annotations Java package](https://github.com/JetBrains/java-annotations/blob/master/common/src/main/java/org/jetbrains/annotations/ApiStatus.java#L94-L111) +has a similar annotation: `@ApiStatus.ScheduledForRemoval`, which allows the library author to specify when an API will be removed from the public API entirely, and is mostly +the inspiration for this RFC. +- The `@Deprecated` attribute from the Java standard library, which has the boolean parameter [`forRemoval`](https://docs.oracle.com/javase%2F9%2Fdocs%2Fapi%2F%2F/java/lang/Deprecated.html#forRemoval--), +it is used to specify whether the deprecated item will be removed in a future version - albeit a bit vague (as it does not allow you to specify which version would the item be removed). + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +- How should this new attribute be named? (Albeit `scheduled_removal` sounds kind of weird to me, it is the currently the best name after discussion +on Rust Internals). + +# Future possibilities +[future-possibilities]: #future-possibilities + +Perhaps other API status attributes can be exposed to library authors, for example `experimental` to mark experimental APIs and emit corresponding +warnings to the user about the usage of an unstable and experimental API of the library, that the code may break at any time without prior notice. From 040a76eb29eeb00715b11144d87898edd9be4833 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 12:50:52 +0800 Subject: [PATCH 02/14] Rename 0000-deprecated-scheduled-removal.md to text/0000-deprecated-scheduled-removal.md --- .../0000-deprecated-scheduled-removal.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename 0000-deprecated-scheduled-removal.md => text/0000-deprecated-scheduled-removal.md (100%) diff --git a/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md similarity index 100% rename from 0000-deprecated-scheduled-removal.md rename to text/0000-deprecated-scheduled-removal.md From f6f33ee9702827d017925e2a034ac700b0dbcb44 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 12:53:31 +0800 Subject: [PATCH 03/14] Add Link to Rust Internals Thread --- text/0000-deprecated-scheduled-removal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 2e5a354ae6c..457bebcc5e2 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -93,8 +93,8 @@ it is used to specify whether the deprecated item will be removed in a future ve # Unresolved questions [unresolved-questions]: #unresolved-questions -- How should this new attribute be named? (Albeit `scheduled_removal` sounds kind of weird to me, it is the currently the best name after discussion -on Rust Internals). +- How should this new attribute be named? (Albeit `scheduled_removal` sounds kind of weird to me, it is the currently the best name after [discussion +on Rust Internals](https://internals.rust-lang.org/t/pre-rfc-scheduled-removal-parameter-for-deprecated-attribute/19324)). # Future possibilities [future-possibilities]: #future-possibilities From 1d3c58ae45785b53a166fe07f08f66df88793993 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:05:15 +0800 Subject: [PATCH 04/14] Update Diagnostics --- text/0000-deprecated-scheduled-removal.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 457bebcc5e2..b1e09ade106 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -1,4 +1,4 @@ -- Feature Name: `deprecated_scheduled_removal` +- Feature Name: deprecated_scheduled_removal - Start Date: 2023-08-13 - RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) - Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) @@ -38,7 +38,7 @@ warning: use of deprecated unit struct `ThisItemIsDeprecated` 5 | let _ = ThisItemIsDeprecated; | ^^^^^^^^^^^^^^^^^^^^ | - = note: this deprecated item will be removed in version 0.3.0 + = note: this deprecated unit struct will be removed in version 0.3.0 = note: `#[warn(deprecated)]` on by default ``` The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version @@ -72,7 +72,7 @@ warning: use of unit struct `ThisItemIsDeprecated` that is scheduled for removal 5 | let _ = ThisItemIsDeprecated; | ^^^^^^^^^^^^^^^^^^^^ | - = note: this item will be removed in version 0.3.0 + = note: this unit struct will be removed in version 0.3.0 = note: `#[warn(scheduled_for_removal)]` on by default ``` The `scheduled_for_removal` lint would be introduced alongside with this attribute. From 10ceabaf2bf72bb9b0d063a84e8d4bec4c59be83 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:12:16 +0800 Subject: [PATCH 05/14] Add RLE --- text/0000-deprecated-scheduled-removal.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index b1e09ade106..dc7b4de3267 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -21,7 +21,6 @@ usually not prepared for sudden removal of deprecated items. Having a `scheduled_removal` attribute, that specifies the version of which a deprecated item is removed would mean users obtain the information of when the deprecated item will be removed from the public API and hence can prepare or complete for the migration beforehand. - # Guide-level explanation [guide-level-explanation]: #guide-level-explanation @@ -48,6 +47,12 @@ to compile due to the removal of the API. # Reference-level explanation [reference-level-explanation]: #reference-level-explanation +The `scheduled_removal` parameter takes in a `&str` value, signifying the version for which the deprecated item is scheduled to be removed. + +The compiler takes this parameter into account when generating diagnostics for usages of an item marked as `#[deprecated]` using this parameter, +appending a `note` line that reads: `this deprecated {item_type} will be removed in version {version}`, where `{item type}` is the type of item +used, like a `unit struct` in this example, and the `{version}` being the version specified as the value to the `scheduled_removal` parameter. + # Drawbacks [drawbacks]: #drawbacks @@ -95,9 +100,10 @@ it is used to specify whether the deprecated item will be removed in a future ve - How should this new attribute be named? (Albeit `scheduled_removal` sounds kind of weird to me, it is the currently the best name after [discussion on Rust Internals](https://internals.rust-lang.org/t/pre-rfc-scheduled-removal-parameter-for-deprecated-attribute/19324)). +- How should the diagnostics be updated to accommodate for this? Currently, simply a `note` line is added. Is that good enough? # Future possibilities [future-possibilities]: #future-possibilities -Perhaps other API status attributes can be exposed to library authors, for example `experimental` to mark experimental APIs and emit corresponding -warnings to the user about the usage of an unstable and experimental API of the library, that the code may break at any time without prior notice. +Other API status attributes can be exposed to library authors, for example `experimental` to mark experimental APIs and emit corresponding warnings to the +user about the usage of an unstable and experimental API of the library, that the code may break at any time without prior notice. From 6e38d41c5b73564975bc266e8a373652c35bbb67 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:22:35 +0800 Subject: [PATCH 06/14] Reword Drawback --- text/0000-deprecated-scheduled-removal.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index dc7b4de3267..47533abaae9 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -56,7 +56,8 @@ used, like a `unit struct` in this example, and the `{version}` being the versio # Drawbacks [drawbacks]: #drawbacks -- More work for library authors to utilise this parameter for enhanced user experience of the users. +- While knowing the version in which the item will be removed is a good thing for the library users, always requiring to put a version is not good, +since putting a specific version then forces the maintainer to remove those items in that specific version. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives From 45d684f98305bf014242d0aa22174e2593e8f2ac Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:27:38 +0800 Subject: [PATCH 07/14] Make Values Optional --- text/0000-deprecated-scheduled-removal.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 47533abaae9..21fe623b6e2 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -24,7 +24,7 @@ of when the deprecated item will be removed from the public API and hence can pr # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example: +This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example, when a version is specified: ```rust #[deprecated(since = "0.2.1", scheduled_removal = "0.3.0")] struct ThisItemIsDeprecated; @@ -40,9 +40,24 @@ warning: use of deprecated unit struct `ThisItemIsDeprecated` = note: this deprecated unit struct will be removed in version 0.3.0 = note: `#[warn(deprecated)]` on by default ``` -The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version -`0.3.0` and would make it clear that the user needs to migrate to another API before `0.3.0` lands, otherwise their code would break and fail -to compile due to the removal of the API. +The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version `0.3.0` and would make it clear that the user needs to migrate to another API before `0.3.0` lands, otherwise their code would break and fail to compile due to the removal of the API. + +If no value is provided for the `scheduled_removal` parameter, like so: +```rust +#[deprecated(since = "0.2.1", scheduled_removal = "0.3.0")] +struct ThisItemIsDeprecated; +``` +Then the usages of this struct would result in the following warning: +``` +warning: use of deprecated unit struct `ThisItemIsDeprecated` + --> src/main.rs:5:17 + | +5 | let _ = ThisItemIsDeprecated; + | ^^^^^^^^^^^^^^^^^^^^ + | + = note: this deprecated unit struct will be removed in a future version + = note: `#[warn(deprecated)]` on by default +``` # Reference-level explanation [reference-level-explanation]: #reference-level-explanation From 442bf037f284b145b026b5a726688225fc1ef644 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:29:16 +0800 Subject: [PATCH 08/14] Move Drawback to Second Example in GLE --- text/0000-deprecated-scheduled-removal.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 21fe623b6e2..5c99a4b2b7a 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -24,7 +24,8 @@ of when the deprecated item will be removed from the public API and hence can pr # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example, when a version is specified: +This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example, when a version +is specified: ```rust #[deprecated(since = "0.2.1", scheduled_removal = "0.3.0")] struct ThisItemIsDeprecated; @@ -59,6 +60,9 @@ warning: use of deprecated unit struct `ThisItemIsDeprecated` = note: `#[warn(deprecated)]` on by default ``` +The second case is particularly useful - while knowing the version in which the item will be removed is a good thing for the library users, always requiring +to put a version is troublesome, as putting a specific version then forces the maintainer to remove those items in that specific version. + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -71,8 +75,7 @@ used, like a `unit struct` in this example, and the `{version}` being the versio # Drawbacks [drawbacks]: #drawbacks -- While knowing the version in which the item will be removed is a good thing for the library users, always requiring to put a version is not good, -since putting a specific version then forces the maintainer to remove those items in that specific version. +None. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives From 36f9b8ee6109fdab8648ef81be2a08cf3d1900ad Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:31:45 +0800 Subject: [PATCH 09/14] Update RLE --- text/0000-deprecated-scheduled-removal.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 5c99a4b2b7a..54f84b5223a 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -66,11 +66,14 @@ to put a version is troublesome, as putting a specific version then forces the m # Reference-level explanation [reference-level-explanation]: #reference-level-explanation -The `scheduled_removal` parameter takes in a `&str` value, signifying the version for which the deprecated item is scheduled to be removed. +The `scheduled_removal` parameter optionally takes in a `&str` value, signifying the version for which the deprecated item is scheduled to be removed. -The compiler takes this parameter into account when generating diagnostics for usages of an item marked as `#[deprecated]` using this parameter, -appending a `note` line that reads: `this deprecated {item_type} will be removed in version {version}`, where `{item type}` is the type of item -used, like a `unit struct` in this example, and the `{version}` being the version specified as the value to the `scheduled_removal` parameter. +The compiler takes this parameter into account when generating diagnostics for usages of an item marked as `#[deprecated]` using this parameter. + +If a version is provided, the compiler will +append a `note` line that reads: `this deprecated {item_type} will be removed in version {version}`, where `{item type}` is the type of item +used, like a `unit struct` in this example, and the `{version}` being the version specified as the value to the `scheduled_removal` parameter. Otherwise, +the appended note line would read like `this deprecated {item_type} will be removed in a future version`, # Drawbacks [drawbacks]: #drawbacks From 591bbf5c3db314dc8a8d02b01a607da8509601a3 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 13:32:30 +0800 Subject: [PATCH 10/14] Fix Formatting --- text/0000-deprecated-scheduled-removal.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 54f84b5223a..acf63b58142 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -70,10 +70,9 @@ The `scheduled_removal` parameter optionally takes in a `&str` value, signifying The compiler takes this parameter into account when generating diagnostics for usages of an item marked as `#[deprecated]` using this parameter. -If a version is provided, the compiler will -append a `note` line that reads: `this deprecated {item_type} will be removed in version {version}`, where `{item type}` is the type of item -used, like a `unit struct` in this example, and the `{version}` being the version specified as the value to the `scheduled_removal` parameter. Otherwise, -the appended note line would read like `this deprecated {item_type} will be removed in a future version`, +If a version is provided, the compiler will append a `note` line that reads: `this deprecated {item_type} will be removed in version {version}`, +where `{item type}` is the type of item used, like a `unit struct` in this example, and the `{version}` being the version specified as the value +to the `scheduled_removal` parameter. Otherwise, the appended note line would read like `this deprecated {item_type} will be removed in a future version`. # Drawbacks [drawbacks]: #drawbacks From 4eceabb625d393feeff9af0e0ebd6d27083493f2 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 14:03:45 +0800 Subject: [PATCH 11/14] Update RLE --- text/0000-deprecated-scheduled-removal.md | 24 ++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index acf63b58142..8a97df5ff83 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -41,7 +41,8 @@ warning: use of deprecated unit struct `ThisItemIsDeprecated` = note: this deprecated unit struct will be removed in version 0.3.0 = note: `#[warn(deprecated)]` on by default ``` -The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version `0.3.0` and would make it clear that the user needs to migrate to another API before `0.3.0` lands, otherwise their code would break and fail to compile due to the removal of the API. +The added line `note: this deprecated item will be removed in version 0.3.0` tells the user this deprecated item will be removed in version `0.3.0` and would +make it clear that the user needs to migrate to another API before `0.3.0` lands, otherwise their code would break and fail to compile due to the removal of the API. If no value is provided for the `scheduled_removal` parameter, like so: ```rust @@ -84,13 +85,13 @@ None. ## A separate `scheduled_for_removal` attribute -A separate attribute named `scheduled_for_removal` will be introduced. Usage of this attribute looks like: +A separate attribute named `scheduled_for_removal` will be introduced. Usage of this attribute looks like, when a version is provided: ```rust #[deprecated(since = "0.2.1")] #[scheduled_for_removal(at = "0.3.0")] struct ThisItemIsDeprecated; ``` -Which would generate the following warning: +Which would result in the following warning: ``` warning: use of unit struct `ThisItemIsDeprecated` that is scheduled for removal --> src/main.rs:5:17 @@ -101,6 +102,23 @@ warning: use of unit struct `ThisItemIsDeprecated` that is scheduled for removal = note: this unit struct will be removed in version 0.3.0 = note: `#[warn(scheduled_for_removal)]` on by default ``` + +When a version is not specified: +```rust +#[deprecated(since = "0.2.1")] +#[scheduled_for_removal] +struct ThisItemIsDeprecated; +``` +Which would result in the following warning: +``` +warning: use of unit struct `ThisItemIsDeprecated` that is scheduled for removal + --> src/main.rs:5:17 + | +5 | let _ = ThisItemIsDeprecated; + | ^^^^^^^^^^^^^^^^^^^^ + | + = note: `#[warn(scheduled_for_removal)]` on by default +``` The `scheduled_for_removal` lint would be introduced alongside with this attribute. This was briefly considered but ultimately personally vetoed because another attribute is quite some work, and it is like an extension to the `deprecated` From 694cd00beb601835e762b4629f6df3a83559e8d4 Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Sun, 13 Aug 2023 20:11:10 +0800 Subject: [PATCH 12/14] Fix Typo --- text/0000-deprecated-scheduled-removal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 8a97df5ff83..6d7f395d8c9 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -46,7 +46,7 @@ make it clear that the user needs to migrate to another API before `0.3.0` lands If no value is provided for the `scheduled_removal` parameter, like so: ```rust -#[deprecated(since = "0.2.1", scheduled_removal = "0.3.0")] +#[deprecated(since = "0.2.1", scheduled_removal)] struct ThisItemIsDeprecated; ``` Then the usages of this struct would result in the following warning: From a44b94d7f06948abeefd8d56b1663398a6d76edd Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Mon, 21 Aug 2023 22:14:00 +0800 Subject: [PATCH 13/14] Note that it is a hard error not removing an item scheduled removal after the scheduled version is reached --- text/0000-deprecated-scheduled-removal.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 6d7f395d8c9..833ffc5e73f 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -24,6 +24,8 @@ of when the deprecated item will be removed from the public API and hence can pr # Guide-level explanation [guide-level-explanation]: #guide-level-explanation +## From Library User Point-of-view + This RFC proposes the addition of the `scheduled_removal` parameter to the `deprecated` attribute, as with the following example, when a version is specified: ```rust @@ -64,6 +66,11 @@ warning: use of deprecated unit struct `ThisItemIsDeprecated` The second case is particularly useful - while knowing the version in which the item will be removed is a good thing for the library users, always requiring to put a version is troublesome, as putting a specific version then forces the maintainer to remove those items in that specific version. +## From Library Author Point-of-view + +For all items annotated with the `deprecated` attribute including this `scheduled_removal` parameter, it is a hard compiler error not removing a certain item +for when the version of the crate is **larger than or equal** to the version specified in the `scheduled_removal` parameter. + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation From 4275861a785cb6616ad33a27ca850db63dbb377c Mon Sep 17 00:00:00 2001 From: HTGAzureX1212 <39023054+HTGAzureX1212@users.noreply.github.com> Date: Mon, 1 Jan 2024 19:00:09 +0800 Subject: [PATCH 14/14] Provide suggestion over the naming of the field --- text/0000-deprecated-scheduled-removal.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-deprecated-scheduled-removal.md b/text/0000-deprecated-scheduled-removal.md index 833ffc5e73f..fc9b5440a7e 100644 --- a/text/0000-deprecated-scheduled-removal.md +++ b/text/0000-deprecated-scheduled-removal.md @@ -146,6 +146,8 @@ it is used to specify whether the deprecated item will be removed in a future ve - How should this new attribute be named? (Albeit `scheduled_removal` sounds kind of weird to me, it is the currently the best name after [discussion on Rust Internals](https://internals.rust-lang.org/t/pre-rfc-scheduled-removal-parameter-for-deprecated-attribute/19324)). + - The name `scheduled_removal` seems to be a bit long given that it is a hard compile error not to remove a certain item after its scheduled removal version. + Can the `scheduled_` prefix be removed? - How should the diagnostics be updated to accommodate for this? Currently, simply a `note` line is added. Is that good enough? # Future possibilities