Skip to content

Commit

Permalink
Merge pull request #3830 from epage/deprecate
Browse files Browse the repository at this point in the history
fix: Allow people to opt-in to deprecations
  • Loading branch information
epage authored Jun 14, 2022
2 parents d71e38e + 7515bfe commit b619699
Show file tree
Hide file tree
Showing 19 changed files with 906 additions and 402 deletions.
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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))

Expand Down
3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
18 changes: 12 additions & 6 deletions src/builder/action.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit b619699

Please sign in to comment.