From 5f8d2ce984c83fa372c08de1001d5eda85e5a626 Mon Sep 17 00:00:00 2001 From: Ben Villalobos Date: Fri, 2 Oct 2020 16:11:57 -0700 Subject: [PATCH 1/4] Refresh docs for an easier read --- documentation/wiki/ChangeWaves-Dev.md | 6 ++---- documentation/wiki/ChangeWaves.md | 17 +++++++++-------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/documentation/wiki/ChangeWaves-Dev.md b/documentation/wiki/ChangeWaves-Dev.md index b740e545ecd..7e6976a7943 100644 --- a/documentation/wiki/ChangeWaves-Dev.md +++ b/documentation/wiki/ChangeWaves-Dev.md @@ -1,12 +1,10 @@ ⚠ 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 version in which a set of risky features 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. ## How do they work? -The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the wave (or version) that contains the feature you want **disabled**. - -**Note:** If `MSBuildDisableFeaturesFromVersion` is set to `16.8`, this will **disable** all features under that `16.8` and **any further versions**. +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**. ## What Are the Current Change Waves & Associated Features? See the mapping of change waves to features [here](ChangeWaves.md#change-waves-&-associated-features). diff --git a/documentation/wiki/ChangeWaves.md b/documentation/wiki/ChangeWaves.md index fd30e1a6fad..9cb7d509ce2 100644 --- a/documentation/wiki/ChangeWaves.md +++ b/documentation/wiki/ChangeWaves.md @@ -1,15 +1,16 @@ # 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 version in which a set of risky features 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. ## How do they work? -The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the 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**. See the mapping of change waves to features below. -**Note:** If `MSBuildDisableFeaturesFromVersion` is set to `16.8`, this will **disable** all features under that `16.8` and **any further versions**. - -## MSBuildDisableFeaturesFromVersion Values -- If `MSBuildDisableFeaturesFromVersion` is not set, all change waves will **be enabled** -- If `MSBuildDisableFeaturesFromVersion` is set to some out of bounds version (see current rotation of waves below), you will be defaulted to the lowest wave. This will **disable all waves**. -- If `MSBuildDisableFeaturesFromVersion` is set to some invalid format (ex: 16x8, 17_0), all change waves will **be enabled**. +## MSBuildDisableFeaturesFromVersion Values & Outcomes +| `MSBuildDisableFeaturesFromVersion` Value | Result | Receive Warning? | +| :------------- | :---------- | :----------: | +| Unset | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled. | No | +| `16.8` (or any valid & current Change Wave) | All features behind the `16.8` and above Change Wave will be disabled . | No | +| Invalid Value (Invalid Change Wave, or out-of-rotation version) | You will be defaulted to the closest valid value (ascending). Ex: Setting `16.9` will default you to `16.10`. | Yes | +| Invalid Format (ex: `16x8`, `17_0`, `garbage`) | All waves will be enabled. | Yes | # Change Waves & Associated Features From 27da04e1a1f25c85686c2e0529d49b6a7eca2fce Mon Sep 17 00:00:00 2001 From: Ben Villalobos Date: Fri, 2 Oct 2020 16:14:21 -0700 Subject: [PATCH 2/4] fix sentence --- documentation/wiki/ChangeWaves-Dev.md | 2 +- documentation/wiki/ChangeWaves.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/wiki/ChangeWaves-Dev.md b/documentation/wiki/ChangeWaves-Dev.md index 7e6976a7943..95a09278acc 100644 --- a/documentation/wiki/ChangeWaves-Dev.md +++ b/documentation/wiki/ChangeWaves-Dev.md @@ -1,7 +1,7 @@ ⚠ This doc is intended for internal teams. # What are Change Waves? -A Change Wave is a version in which a set of risky features 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 version in which a set of risky features exists 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. ## 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**. diff --git a/documentation/wiki/ChangeWaves.md b/documentation/wiki/ChangeWaves.md index 9cb7d509ce2..5d6fc660c8a 100644 --- a/documentation/wiki/ChangeWaves.md +++ b/documentation/wiki/ChangeWaves.md @@ -1,5 +1,5 @@ # What are Change Waves? -A Change Wave is a version in which a set of risky features 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 version in which a set of risky features exists 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. ## 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. From cafcec6bb26f6e8859d6e576a1b9e8d724a5c4ac Mon Sep 17 00:00:00 2001 From: Ben Villalobos Date: Mon, 5 Oct 2020 11:39:43 -0700 Subject: [PATCH 3/4] PR Feedback --- documentation/wiki/ChangeWaves-Dev.md | 14 +++++++------- documentation/wiki/ChangeWaves.md | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/documentation/wiki/ChangeWaves-Dev.md b/documentation/wiki/ChangeWaves-Dev.md index 95a09278acc..e23870c88c8 100644 --- a/documentation/wiki/ChangeWaves-Dev.md +++ b/documentation/wiki/ChangeWaves-Dev.md @@ -1,10 +1,10 @@ ⚠ This doc is intended for internal teams. # What are Change Waves? -A Change Wave is a version in which a set of risky features exists 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. 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. ## 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**. +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. ## What Are the Current Change Waves & Associated Features? See the mapping of change waves to features [here](ChangeWaves.md#change-waves-&-associated-features). @@ -24,10 +24,10 @@ The Process: 1. In the `Microsoft.Build` project, open `SharedUtilities\ChangeWaves.cs`. 2. Add a const string to identify the new wave, following the format: ```c# -public const string Wave17_4 = "17.4" +public const string Wave17_4 = "17.4"; ``` 3. You may need to delete the lowest wave as new waves get added. -4. As you rotate in/out change waves, be sure to update the AllWaves array appropriately. +4. Update the AllWaves array appropriately. ```c# public static readonly string[] AllWaves = { Wave16_10, Wave17_0, Wave17_4 }; ``` @@ -79,9 +79,9 @@ using (TestEnvironment env = TestEnvironment.Create()) } ``` -## Change Wave 'End of Lifespan' Procedure +## Change Wave 'End-of-Lifespan' Procedure These features will eventually become standard functionality. When a change wave rotates out, do the following: -1. Start by deleting the constant `Wave17_4` that was created in step one. -2. Remove `ChangeWave.AreFeaturesEnabled` or `$([MSBuild]::AreFeaturesEnabled('17.4'))` conditions surrounding features that were assigned that 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. \ No newline at end of file diff --git a/documentation/wiki/ChangeWaves.md b/documentation/wiki/ChangeWaves.md index 5d6fc660c8a..9a487cc488d 100644 --- a/documentation/wiki/ChangeWaves.md +++ b/documentation/wiki/ChangeWaves.md @@ -1,5 +1,5 @@ # What are Change Waves? -A Change Wave is a version in which a set of risky features exists 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. 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. ## 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. @@ -8,7 +8,7 @@ The opt out comes in the form of setting the environment variable `MSBuildDisabl | `MSBuildDisableFeaturesFromVersion` Value | Result | Receive Warning? | | :------------- | :---------- | :----------: | | Unset | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled. | No | -| `16.8` (or any valid & current Change Wave) | All features behind the `16.8` and above Change Wave will be disabled . | No | +| `16.8` (or any valid & current Change Wave) | All features behind Change Wave `16.8` and higher will be disabled. | No | | Invalid Value (Invalid Change Wave, or out-of-rotation version) | You will be defaulted to the closest valid value (ascending). Ex: Setting `16.9` will default you to `16.10`. | Yes | | Invalid Format (ex: `16x8`, `17_0`, `garbage`) | All waves will be enabled. | Yes | From 315b7415f0e3a380c4d73a697b621eeba5277134 Mon Sep 17 00:00:00 2001 From: Ben Villalobos Date: Mon, 5 Oct 2020 12:18:07 -0700 Subject: [PATCH 4/4] PR Feedback --- documentation/wiki/ChangeWaves-Dev.md | 2 +- documentation/wiki/ChangeWaves.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/documentation/wiki/ChangeWaves-Dev.md b/documentation/wiki/ChangeWaves-Dev.md index e23870c88c8..b891f1f728c 100644 --- a/documentation/wiki/ChangeWaves-Dev.md +++ b/documentation/wiki/ChangeWaves-Dev.md @@ -82,6 +82,6 @@ using (TestEnvironment env = TestEnvironment.Create()) ## Change Wave 'End-of-Lifespan' Procedure These features will eventually become standard functionality. When a change wave rotates out, do the following: 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. +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. \ No newline at end of file diff --git a/documentation/wiki/ChangeWaves.md b/documentation/wiki/ChangeWaves.md index 9a487cc488d..4173d2ae42a 100644 --- a/documentation/wiki/ChangeWaves.md +++ b/documentation/wiki/ChangeWaves.md @@ -8,9 +8,10 @@ The opt out comes in the form of setting the environment variable `MSBuildDisabl | `MSBuildDisableFeaturesFromVersion` Value | Result | Receive Warning? | | :------------- | :---------- | :----------: | | Unset | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled. | No | -| `16.8` (or any valid & current Change Wave) | All features behind Change Wave `16.8` and higher will be disabled. | No | -| Invalid Value (Invalid Change Wave, or out-of-rotation version) | You will be defaulted to the closest valid value (ascending). Ex: Setting `16.9` will default you to `16.10`. | Yes | -| Invalid Format (ex: `16x8`, `17_0`, `garbage`) | All waves will be enabled. | Yes | +| Any valid & current Change Wave (Ex: `16.8`) | All features behind Change Wave `16.8` and higher will be disabled. | No | +| Invalid Value (Ex: `16.9` when valid waves are `16.8` and `16.10`)| Default to the closest valid value (ascending). Ex: Setting `16.9` will default you to `16.10`. | No | +| Out of Rotation (Ex: `17.1` when the highest wave is `17.0`) | Clamp to the closest valid value. Ex: `17.1` clamps to `17.0`, and `16.5` clamps to `16.8` | Yes | +| Invalid Format (Ex: `16x8`, `17_0`, `garbage`) | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled. | Yes | # Change Waves & Associated Features