fix: Allow people to opt-in to deprecations

This adds a new `Cargo.toml` feature named `deprecated` that opts
controls whether deprecation warnings show up.  This is starting off as
non-default though that may change (see below).

Benefits
- Allows a staged rollout so a smaller subset of users see new
  deprecations and can report their experience with them before everyone
  sees them.  For example, this reduces the number of people who have to
  deal with #3822.
- This allows people to defer responding to each new batch of
  deprecations and instead do it at once.  This means we should
  reconsider #3616.

The one risk is people who don't follow blog posts and guides having a
harder time upgrading to the next breaking release without the warnings
on by default.  For these users, we reserve the right to make the
`deprecated` feature `default`.  This is most likely to happen in a
minor release that is released in conjunction with the next major
release (e.g. when releasing 4.0.0, we release a 3.3.0 that enables
deprecations by default).  By using a feature, users can still disable
this if they want.

Thanks @joshtriplett for the idea

Author: epage

CONTRIBUTING.md

@@ -38,10 +38,12 @@ Our releases fall into one of:
   - Aspire to at least 6-9 months between releases
   - Remove all deprecated functionality
   - Try to minimize new breaking changes to ease user transition and reduce time "we go dark" (unreleased feature-branch)
+  - Upon release, a minor release will be made for the previous major that enables `deprecated` feature by default
 - Minor releases which are for minor compatibility changes
   - Aspire to at least 2 months between releases
   - Changes to MSRV
-  - Deprecating existing functionality
+  - Deprecating existing functionality (behind the `deprecated` feature flag)
+  - Making the `deprecated` feature flag enabled-by-default (only on last planned minor release)
   - `#[doc(hidden)]` all deprecated items in the prior minor release
 - Patch releases
   - One for every user-facing, user-contributed PR (i.e. release early, release often)
@@ -51,7 +53,7 @@ If your change does not fit within a "patch" release, please coordinate with the
 Some practices to avoid breaking changes
 - Duplicate functionality, with old functionality marked as "deprecated"
   - Common documentation pattern: `/// Deprecated in [Issue #XXX](https://github.com/clap-rs/clap/issues/XXX), replaced with [intra-doc-link]`
-  - Common deprecation pattern: `#[deprecated(since = "X.Y.Z", note = "Replaced with `ITEM` in Issue #XXX")]`
+  - Common deprecation pattern: `#[cfg_attr(feature = "deprecated", deprecated(since = "X.Y.Z", note = "Replaced with `ITEM` in Issue #XXX"))]`
   - Please keep API addition and deprecation in separate commits in a PR to make it easier to review
 - Develop the feature behind an `unstable-<name>` feature flag with a stablization tracking issue (e.g. [Multicall Tracking issue](https://github.com/clap-rs/clap/issues/2861))
 

Cargo.toml

@@ -73,6 +73,7 @@ color = ["atty", "termcolor"]
 suggestions = ["strsim"]
 
 # Optional
+deprecated = [] # Guided experience to prepare for next breaking release (at different stages of development, this may become default)
 derive = ["clap_derive", "once_cell"]
 cargo = ["once_cell"] # Disable if you're not using Cargo, enables Cargo-env-var-dependent macros
 wrap_help = ["terminal_size", "textwrap/terminal_size"]
@@ -84,7 +85,7 @@ unicode = ["textwrap/unicode-width", "unicase"]  # Support for unicode character
 unstable-replace = []
 unstable-grouped = []
 # note: this will always enable clap_derive, change this to `clap_derive?/unstable-v4` when MSRV is bigger than 1.60
-unstable-v4 = ["clap_derive/unstable-v4"]
+unstable-v4 = ["clap_derive/unstable-v4", "deprecated"]
 
 [lib]
 bench = false

Makefile

@@ -15,8 +15,8 @@ MSRV?=1.56.0
 _FEATURES = minimal default wasm full debug release
 _FEATURES_minimal = --no-default-features --features "std"
 _FEATURES_default =
-_FEATURES_wasm = --features "derive cargo env unicode yaml regex unstable-replace unstable-grouped"
-_FEATURES_full = --features "derive cargo env unicode yaml regex unstable-replace unstable-grouped wrap_help"
+_FEATURES_wasm = --features "deprecated derive cargo env unicode yaml regex unstable-replace unstable-grouped"
+_FEATURES_full = --features "deprecated derive cargo env unicode yaml regex unstable-replace unstable-grouped wrap_help"
 _FEATURES_next = ${_FEATURES_full} --features unstable-v4
 _FEATURES_debug = ${_FEATURES_full} --features debug
 _FEATURES_release = ${_FEATURES_full} --release

README.md

@@ -140,6 +140,7 @@ Why use the procedural [Builder API](https://github.com/clap-rs/clap/blob/v3.2.2
 
 #### Optional features
 
+* **deprecated**: Guided experience to prepare for next breaking release (at different stages of development, this may become default)
 * **derive**: Enables the custom derive (i.e. `#[derive(Parser)]`). Without this you must use one of the other methods of creating a `clap` CLI listed above.
 * **cargo**: Turns on macros that read values from `CARGO_*` environment variables.
 * **env**: Turns on the usage of environment variables during parsing.

src/builder/action.rs

@@ -71,15 +71,21 @@ pub enum ArgAction {
     /// ```
     Append,
     /// Deprecated, replaced with [`ArgAction::Set`] or [`ArgAction::Append`]
-    #[deprecated(
-        since = "3.2.0",
-        note = "Replaced with `ArgAction::Set` or `ArgAction::Append`"
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(
+            since = "3.2.0",
+            note = "Replaced with `ArgAction::Set` or `ArgAction::Append`"
+        )
     )]
     StoreValue,
     /// Deprecated, replaced with [`ArgAction::SetTrue`] or [`ArgAction::Count`]
-    #[deprecated(
-        since = "3.2.0",
-        note = "Replaced with `ArgAction::SetTrue` or `ArgAction::Count`"
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(
+            since = "3.2.0",
+            note = "Replaced with `ArgAction::SetTrue` or `ArgAction::Count`"
+        )
     )]
     IncOccurrence,
     /// When encountered, act as if `"true"` was encountered on the command-line