Auto merge of #10868 - Muscraft:add-reason-for-nightly-tests, r=ehuss

add a reason to `masquerade_as_nightly_cargo` so it is searchable

When I was working on the stabilization for workspace inheritance, it was very tedious to find all of the places to remove `.masquerade_as_nightly_cargo()`. I [suggested](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/problems.20finding.20.60.2Emasquerade_as_nightly_cargo.28.29.60) to add a reason to `.masquerade_as_nightly_cargo()` so that it would be easier to find all of the places to remove it. By adding the reason it makes it easy to search for all places with the features name. This PR adds the reason(s) to all of the places `.masquerade_as_nightly_cargo()` is called, as well as updates the documentation so it talks about adding a reason when making the call.

crates/cargo-test-support/src/lib.rs

@@ -806,9 +806,14 @@ impl Execs {
         p.build_command()
     }
 
-    pub fn masquerade_as_nightly_cargo(&mut self) -> &mut Self {
+    /// Enables nightly features for testing
+    ///
+    /// The list of reasons should be why nightly cargo is needed. If it is
+    /// becuase of an unstable feature put the name of the feature as the reason,
+    /// e.g. `&["print-im-a-teapot"]`
+    pub fn masquerade_as_nightly_cargo(&mut self, reasons: &[&str]) -> &mut Self {
         if let Some(ref mut p) = self.process_builder {
-            p.masquerade_as_nightly_cargo();
+            p.masquerade_as_nightly_cargo(reasons);
         }
         self
     }
@@ -1139,17 +1144,20 @@ fn _process(t: &OsStr) -> ProcessBuilder {
 
 /// Enable nightly features for testing
 pub trait ChannelChanger {
-    fn masquerade_as_nightly_cargo(self) -> Self;
+    /// The list of reasons should be why nightly cargo is needed. If it is
+    /// becuase of an unstable feature put the name of the feature as the reason,
+    /// e.g. `&["print-im-a-teapot"]`.
+    fn masquerade_as_nightly_cargo(self, _reasons: &[&str]) -> Self;
 }
 
 impl ChannelChanger for &mut ProcessBuilder {
-    fn masquerade_as_nightly_cargo(self) -> Self {
+    fn masquerade_as_nightly_cargo(self, _reasons: &[&str]) -> Self {
         self.env("__CARGO_TEST_CHANNEL_OVERRIDE_DO_NOT_USE_THIS", "nightly")
     }
 }
 
 impl ChannelChanger for snapbox::cmd::Command {
-    fn masquerade_as_nightly_cargo(self) -> Self {
+    fn masquerade_as_nightly_cargo(self, _reasons: &[&str]) -> Self {
         self.env("__CARGO_TEST_CHANNEL_OVERRIDE_DO_NOT_USE_THIS", "nightly")
     }
 }

src/cargo/core/features.rs

@@ -86,7 +86,9 @@
 //!      `CliUnstable. Remove the `(unstable)` note in the clap help text if
 //!      necessary.
 //! 2. Remove `masquerade_as_nightly_cargo` from any tests, and remove
-//!    `cargo-features` from `Cargo.toml` test files if any.
+//!    `cargo-features` from `Cargo.toml` test files if any. You can
+//!     quickly find what needs to be removed by searching for the name
+//!     of the feature, e.g. `print_im_a_teapot`
 //! 3. Update the docs in unstable.md to move the section to the bottom
 //!    and summarize it similar to the other entries. Update the rest of the
 //!    documentation to add the new feature.

src/doc/contrib/src/tests/writing.md

@@ -71,11 +71,11 @@ fn <description>() {
 #### Testing Nightly Features
 
 If you are testing a Cargo feature that only works on "nightly" Cargo, then
-you need to call `masquerade_as_nightly_cargo` on the process builder like
-this:
+you need to call `masquerade_as_nightly_cargo` on the process builder and pass 
+the name of the feature as the reason, like this:
 
 ```rust,ignore
-p.cargo("build").masquerade_as_nightly_cargo()
+p.cargo("build").masquerade_as_nightly_cargo(&["print-im-a-teapot"])
 ```
 
 If you are testing a feature that only works on *nightly rustc* (such as
@@ -192,12 +192,12 @@ Be sure to check the snapshots to make sure they make sense.
 #### Testing Nightly Features
 
 If you are testing a Cargo feature that only works on "nightly" Cargo, then
-you need to call `masquerade_as_nightly_cargo` on the process builder like
-this:
+you need to call `masquerade_as_nightly_cargo` on the process builder and pass
+the name of the feature as the reason, like this:
 
 ```rust,ignore
     snapbox::cmd::Command::cargo()
-        .masquerade_as_nightly_cargo()
+        .masquerade_as_nightly_cargo(&["print-im-a-teapot"])
 ```
 
 If you are testing a feature that only works on *nightly rustc* (such as

tests/build-std/main.rs

@@ -32,7 +32,7 @@ fn enable_build_std(e: &mut Execs, arg: Option<&str>) {
         None => "-Zbuild-std".to_string(),
     };
     e.arg(arg);
-    e.masquerade_as_nightly_cargo();
+    e.masquerade_as_nightly_cargo(&["build-std"]);
 }
 
 // Helper methods used in the tests below

tests/testsuite/advanced_env.rs

@@ -31,7 +31,7 @@ fn source_config_env() {
     let path = paths::root().join("registry");
 
     p.cargo("check -Zadvanced-env")
-        .masquerade_as_nightly_cargo()
+        .masquerade_as_nightly_cargo(&["advanced-env"])
         .env("CARGO_SOURCE_crates-io_REPLACE_WITH", "my-local-source")
         .env("CARGO_SOURCE_my-local-source_LOCAL_REGISTRY", path)
         .run();