fix: Allow people to opt-in to deprecations

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