Backport and Deprecations to 0.14.x from 1.0

[seanmonstar]

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)].

[kate-shine]

Personally, I'd prefer it to be an opt-out feature.

• opt-in would, in my experience, result in plenty of projects missing it
• enabling it without any attached feature would, as you said, allow disabling by #[allow(deprecation)], but I don't think I like the idea of allowing deprecation warnings for all crates because of one

[jcgruenhage]

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]

Yea, backports can simply be opt-in: we'll make a cargo feature you can enable, and won't put it in default.

I'd prefer it to be an opt-out feature.

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 the allow directly on the import/use line.

[epage]

clap initially did opt-out but switched to opt-in. clap-rs/clap#3822 is the issue that led us to making the switch.

• Not everyone upgrades at once
• #[allow(deprecated)] is very coarse
• Not everyone is a fan of allowing deprecations in CI (e.g. Reduce warning strictness rust-lang/cargo#10742)

For us, we document in our version migration guide to run cargo check --all-targets -F clap/deprecated before 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]

The clap approach sounds considerate. In line with that and on this point specifically:

We can also add warnings to types or methods which are just completely gone in 1.0.

Warnings that cannot be fixed are probably just going to annoy people, so opt-in, I'd say.

[seanmonstar]

This was mostly done (see #3053 and #3079).