fix: Gate App::replace

We are concerned about the level of polish of this feature and are
unsure enough about its future, we've decided to gate it to unblock the
v3 release.

.github/workflows/ci-pr.yml

@@ -41,7 +41,7 @@ jobs:
   test-full:
     name: Tests (Full)
     env:
-      FLAGS: --features 'wrap_help yaml regex'
+      FLAGS: --features 'wrap_help yaml regex unstable-replace'
     strategy:
       fail-fast: false
       matrix:

.github/workflows/ci.yml

@@ -97,13 +97,13 @@ jobs:
         if: matrix.features == 'all'
         with:
           command: test
-          args: --target ${{ matrix.target }} --features "wrap_help yaml regex"
+          args: --target ${{ matrix.target }} --features "wrap_help yaml regex unstable-replace"
       - name: Check debug
         uses: actions-rs/cargo@v1
         if: matrix.features == 'all'
         with:
           command: check
-          args: --target ${{ matrix.target }} --features "wrap_help yaml regex debug"
+          args: --target ${{ matrix.target }} --features "wrap_help yaml regex unstable-replace debug"
       - name: Test release
         uses: actions-rs/cargo@v1
         if: matrix.features == 'release'
@@ -139,13 +139,13 @@ jobs:
         if: matrix.features == 'all'
         with:
           command: test
-          args: --features "wrap_help yaml regex"
+          args: --features "wrap_help yaml regex unstable-replace"
       - name: Check debug
         uses: actions-rs/cargo@v1
         if: matrix.features == 'all'
         with:
           command: check
-          args: --features "wrap_help yaml regex debug"
+          args: --features "wrap_help yaml regex unstable-replace debug"
       - name: Test release
         uses: actions-rs/cargo@v1
         if: matrix.features == 'release'

CHANGELOG.md

@@ -10,6 +10,8 @@ TODO: `YamlLoader`
 
 * **Renamed Features**
   * `unicode_help` to `unicode` to encompass more functionality
+* **Gated Features**
+  * `App::replace` is now gated behind `unstable-replace`
 
 <a name="v3.0.0-beta.4"></a>
 ## v3.0.0-beta.4 (2021-08-14)

Cargo.toml

@@ -106,6 +106,9 @@ unicode = ["textwrap/unicode-width", "unicase"]  # Support for unicode character
 wrap_help = ["terminal_size", "textwrap/terminal_size"]
 yaml = ["yaml-rust"]
 
+# In-work features
+unstable-replace = []
+
 [profile.test]
 opt-level = 1
 
@@ -114,7 +117,7 @@ lto = true
 codegen-units = 1
 
 [package.metadata.docs.rs]
-features = ["yaml", "regex"]
+features = ["yaml", "regex", "unstable-replace"]
 targets = ["x86_64-unknown-linux-gnu"]
 
 [workspace]

README.md

@@ -503,6 +503,10 @@ features = ["std", "suggestions", "color"]
 * **wrap_help**: Turns on the help text wrapping feature, based on the terminal size. (builds dependency `term-size`)
 * **yaml**: Enables building CLIs from YAML documents. (builds dependency `yaml-rust`)
 
+#### Experimental features
+
+* **unstable-replace**: Enable [`App::replace`](https://github.com/clap-rs/clap/issues/2836)
+
 ### More Information
 
 You can find complete documentation on the [docs.rs][docs] for this project.

src/build/app/mod.rs

@@ -1445,6 +1445,8 @@ impl<'help> App<'help> {
 
     /// Replaces an argument or subcommand used on the CLI at runtime with other arguments or subcommands.
     ///
+    /// **Note:** This is gated behind [`unstable-replace`](https://github.com/clap-rs/clap/issues/2836)
+    ///
     /// When this method is used, `name` is removed from the CLI, and `target`
     /// is inserted in its place. Parsing continues as if the user typed
     /// `target` instead of `name`.
@@ -1547,6 +1549,7 @@ impl<'help> App<'help> {
     ///
     /// [`App::replace`]: App::replace()
     #[inline]
+    #[cfg(feature = "unstable-replace")]
     pub fn replace(mut self, name: &'help str, target: &'help [&'help str]) -> Self {
         self.replacers.insert(name, target);
         self

tests/subcommands.rs

@@ -327,6 +327,7 @@ fn invisible_aliases_help_output() {
 }
 
 #[test]
+#[cfg(feature = "unstable-replace")]
 fn replace() {
     let m = App::new("prog")
         .subcommand(App::new("module").subcommand(App::new("install").about("Install module")))