Update Change Wave Docs (#5851)

* Better messaging on opt-in vs opt-out. partial fix on #5756

documentation/wiki/ChangeWaves-Dev.md

@@ -1,21 +1,24 @@
 ⚠ This doc is intended for internal teams.
 
 # What are Change Waves?
-A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line.
+A Change Wave is a set of risky features developed under the same opt-out flag. The purpose of this is to warn developers of risky changes that will become standard functionality down the line. If there's something we think is worth the risk, we found that Change Waves were a good middle ground between making necessary changes and warning customers of what will soon be permanent.
 
-## How do they work?
-The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. All later change waves are similarly disabled.
+## Why Opt-Out vs. Opt-In?
+Opt-out is a better approach for us because we'd likely get limited feedback when a feature impacts customer builds. When a feature does impact a customer negatively, it's a quick switch to disable and allows time to adapt. The key aspect to Change Waves is that it smooths the transition for customers adapting to risky changes that the MSBuild team feels strongly enough to take.
 
-## What Are the Current Change Waves & Associated Features?
-See the mapping of change waves to features [here](ChangeWaves.md#change-waves-&-associated-features).
+## How do They Work?
+The opt-out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. This version happens to be the version of MSBuild that the features were developed for. See the mapping of change waves to features below.
+
+## Choosing a Change Wave for a New Feature
+This is determined on a case by case basis and should be discussed with the MSBuild team. A safe bet would be to check our [currently active Change Waves](ChangeWaves.md#change-waves-&-associated-features) and pick the version after the latest MSBuild version. This version corresponds to the latest version of Visual Studio.
 
 # Developing With Change Waves in Mind
 For the purpose of providing an example, the rest of this document assumes we're developing a feature for MSBuild version **17.4**.
 
 The Process:
 1. Develop your feature.
-2. [Create the change wave](#creating-a-change-wave) (if necessary)
-3. [Check if your change wave is enabled](#checking-if-a-change-wave-is-enabled)
+2. [Create the Change Wave](#creating-a-change-wave) (if necessary)
+3. [Condition your feature on that Change Wave](#condition-your-feature-on-a-change-wave)
 4. [Test your feature](#test-your-feature)
 5. [Document it](ChangeWaves.md#change-wave-features)
 6. [Delete the wave as it cycles out](#change-wave-'end-of-lifespan'-procedure)
@@ -32,11 +35,11 @@ public const string Wave17_4 = "17.4";
 public static readonly string[] AllWaves = { Wave16_10, Wave17_0, Wave17_4 };
 ```
 
-## Checking If A Change Wave is Enabled
+## Condition Your Feature On A Change Wave
 Surround your feature with the following:
 ```c#
     // If you pass an incorrectly formatted change wave, this will throw.
-    // Use the const string that was created in the previous step.
+    // Use the const Version that was created in the previous step.
     if (ChangeWaves.AreFeaturesEnabled(ChangeWaves.Wave17_4))
     {
         <your feature>
@@ -50,7 +53,13 @@ If you need to condition a Task or Target, use the built in `AreFeaturesEnabled`
 ```
 
 ## Test Your Feature
-Create tests as you normally would. Include one test with environment variable `MSBuildDisableFeaturesFromVersion` set to `ChangeWaves.Wave17_4`.
+Create tests as you normally would. Include one test with environment variable `MSBuildDisableFeaturesFromVersion` set to `ChangeWaves.Wave17_4`. Set this like so:
+```c#
+TestEnvironment env = TestEnvironment.Create()
+
+env.SetChangeWave(ChangeWaves.Wave17_4);
+```
+When the TestEnvironment is disposed, it handles special logic to properly reset Change Waves for future tests.
 
 **Important!** If you need to build a project to test your feature (say, for tasks or targets), build via `ProjectCollection` in your test.
 
@@ -84,4 +93,4 @@ These features will eventually become standard functionality. When a change wave
 1. Start by deleting the constant `Wave17_4` that was created in [Creating a Change Wave](#creating-a-change-wave).
 2. Remove `ChangeWave.AreFeaturesEnabled` or `[MSBuild]::AreFeaturesEnabled` conditions surrounding features that were assigned that change wave.
 3. Remove tests associated with ensuring features would not run if this wave were set.
-4. Clear all other issues that arose from deleting the constant.
+4. Clear all other issues that arose from deleting the constant.

documentation/wiki/ChangeWaves.md

@@ -1,8 +1,11 @@
 # What are Change Waves?
-A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line.
+A Change Wave is a set of risky features developed under the same opt-out flag. The purpose of this is to warn developers of "risky" changes that will become standard functionality down the line. If there's something we think is worth the risk, we found that Change Waves were a good middle ground between making necessary changes and warning customers of what will soon be permanent.
+
+## Why Opt-Out vs. Opt-In?
+Opt-out is a better approach for us because we'd likely get limited feedback when a feature impacts customer builds. When a feature does impact a customer negatively, it's a quick switch to disable and allows time to adapt. The key aspect to Change Waves is that it smooths the transition for customers adapting to risky changes that the MSBuild team feels strongly enough to take.
 
 ## How do they work?
-The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. See the mapping of change waves to features below.
+The opt-out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. This version happens to be the version of MSBuild that the features were developed for. See the mapping of change waves to features below.
 
 ## MSBuildDisableFeaturesFromVersion Values & Outcomes
 | `MSBuildDisableFeaturesFromVersion` Value                         | Result        | Receive Warning? |
@@ -24,4 +27,4 @@ The opt out comes in the form of setting the environment variable `MSBuildDisabl
 
 ### 17.0
 
-## Change Waves No Longer In Rotation
+## Change Waves No Longer In Rotation