Repository navigation
Backport and Deprecations to 0.14.x from 1.0 #3052
Description
In order to ease the upgrade from 0.14.x to 1.0, a big help would be to backport additions from 1.0, and add deprecation warnings of things that will go away. Ideally, this will allow people using 0.14.x versions to start updating their apps and libraries with guides from the compiler, without having to fully swallow the 1.0 pill yet.
Backports
- We can't backport everything. Some of the changes are breaking in nature. We can only backport additions.
Deprecations
- As things are backported, we can add deprecation warnings to the existing types that are removed in 1.0, guiding them to start using the backported APIs.
- We can also add warnings to types or methods which are just completely gone in 1.0.
- For types that are moving to
hyper-util, we could add a weaker deprecation warning, especially if the type that is moving is easy to copy.
Opt-in / Opt-out
- We can create a new cargo feature, such as
1.0-backports(or some better name), so people only compile the backports if they want to use them. - I'm undecided about whether deprecations should be on by default, possibly with an opt-out cargo feature, or only opt-in.
- If they are opt-in, people may not realize they could start preparing early.
- There is already a built-in way to opt-out of a deprecation warning,
#[allow(deprecation)].
Activity
kate-shine commentedon Dec 21, 2022
Personally, I'd prefer it to be an opt-out feature.
#[allow(deprecation)], but I don't think I like the idea of allowing deprecation warnings for all crates because of onejcgruenhage commentedon Dec 21, 2022
A way for the backports to be opt-out would still have to be an opt-in feature that's enabled by default. Features are additive, and should only ever enable new functionality. Code that compiles without a feature enabled should never break when a new feature is enabled. Source: https://doc.rust-lang.org/cargo/reference/features.html?highlight=additive#feature-unification
seanmonstar commentedon Dec 21, 2022
Yea, backports can simply be opt-in: we'll make a cargo feature you can enable, and won't put it in
default.I assume you mean being able to opt-out of the deprecation warnings. Users wouldn't have to
#![allow(deprecated)]and hide all other crates, they can add theallowdirectly on the import/use line.epage commentedon Dec 21, 2022
clap initially did opt-out but switched to opt-in. clap-rs/clap#3822 is the issue that led us to making the switch.
#[allow(deprecated)]is very coarseFor us, we document in our version migration guide to run
cargo check --all-targets -F clap/deprecatedbefore attempting the upgrade (ie generally don't enable it but enable it in one off runs). Granted, a good number of people update without looking at the CHANGELOG and are first to open an Issue or start a Discussion rather than read the CHANGELOG, so it won't help with everyone.stephank commentedon Dec 22, 2022
The clap approach sounds considerate. In line with that and on this point specifically:
Warnings that cannot be fixed are probably just going to annoy people, so opt-in, I'd say.
seanmonstar commentedon Aug 24, 2023
This was mostly done (see #3053 and #3079).