Chore: Add fix & docs for mandatory prod update (#1740)

#### Details

This PR fixes a structural (but non-functional) bug associated with
building mandatory prod updates. I also realized that this behavior
wasn't documented anywhere, so I added an extra bit to the docs. The
integration test that runs during the build now verifies that the
generated value for production minimum version is correct based on the
`IsMandatoryProdUpdate` environment variable.

I ran 3 validation builds:
1. When `IsMandatoryProdUpdate` = "Dave", the build fails in the
integration tests. Log output
([link](https://mseng.visualstudio.com/1ES/_build/results?buildId=24503522&view=logs&j=06f1c8b2-7bb0-5c49-9f03-01a8f16e24cf&t=acaf2a90-5d04-5dbb-0d6a-3dcb39127913&l=4438)):
```
          Failed EmbeddedManifestMatchesRawManifest [172 ms]
          Error Message:
           Assert.IsTrue failed. The IsMandatoryProdUpdate environment variable must be 'true' or 'false' (case sensitive) if it is set.
          Stack Trace:
             at ManifestTests.IntegrationTests.EmbeddedManifestMatchesRawManifest() in 
        D:\a\1\s\src\ManifestTests\IntegrationTests.cs:line 88
```
2. When `IsMandatoryProdUpdate` = "true", the build succeeds and uses
current version as minimum prod version. Log output
([link](https://mseng.visualstudio.com/1ES/_build/results?buildId=24503524&view=logs&j=7c3ebc89-e7dd-5791-8c02-2ea1f3a27b50&t=9b81c1c0-976a-538f-a1e1-f4d170544876&l=3063)):
```
          VERBOSE:   Entering Get-MinimumProductionVersion
          VERBOSE:     currentVersion = 1.1.2532.08
          VERBOSE:     octokitRelativePath = Octokit\9.0.0\lib\netstandard2.0\Octokit.dll
          VERBOSE:     isMandatoryProdUpdate = true
          VERBOSE:     Using currentVersion for minimumProductionVersion
          VERBOSE:   Exiting Get-MinimumProductionVersion with value of 1.1.2532.08
```
3. When `IsMandatoryProdUpdate` = "false", the build succeeds and uses
latest prod release as minimum prod version. Log output
([link](https://mseng.visualstudio.com/1ES/_build/results?buildId=24503525&view=logs&j=7c3ebc89-e7dd-5791-8c02-2ea1f3a27b50&t=9b81c1c0-976a-538f-a1e1-f4d170544876&l=3089))
```
          VERBOSE:   Entering Get-MinimumProductionVersion
          VERBOSE:     currentVersion = 1.1.2532.09
          VERBOSE:     octokitRelativePath = Octokit\9.0.0\lib\netstandard2.0\Octokit.dll
          VERBOSE:     isMandatoryProdUpdate = false
          VERBOSE:     Fetching version from 'https://github.com/microsoft/accessibility-insights-windows/releases/tag/latest'
          VERBOSE:     Entering Get-Client
          VERBOSE:       Relative path to OctoKit.dll = Octokit\9.0.0\lib\netstandard2.0\Octokit.dll
          VERBOSE:       Full path to OctoKit.dll = C:\NuGetPackages\Octokit\9.0.0\lib\netstandard2.0\Octokit.dll
          VERBOSE:     Exiting Get-Client
          VERBOSE:   Exiting Get-MinimumProductionVersion with value of 1.1.2445.01
```

##### Motivation

<!-- This can be as simple as "addresses issue #123" -->

##### Context

<!-- Are there any parts that you've intentionally left out-of-scope for
a later PR to handle? -->

<!-- Were there any alternative approaches you considered? What
tradeoffs did you consider? -->

#### Pull request checklist
<!-- If a checklist item is not applicable to this change, write "n/a"
in the checkbox -->

- [ ] Run through of all [test
scenarios](https://github.com/Microsoft/accessibility-insights-windows/blob/main/docs/Scenarios.md)
completed?
- [n/a] Does this address an existing issue? If yes, Issue# - 
- [n/a] Includes UI changes?
- [n/a] Run the production version of Accessibility Insights for Windows
against a version with changes.
  - [n/a] Attach any screenshots / GIF's that are applicable.

> Note: After the PR has been created, certain checks will be kicked
off. All of these checks must pass before a merge.

docs/ChangingVersions.md

@@ -13,6 +13,15 @@ This is the most common scenario that leads to a version change. The process wor
 - It exits the application after the VersionSwitcher has successfully launched with administrative privilege.
 - It includes telemetry results written by the VersionSwitcher on its next boot.
 
+#### Update policies
+- In the **Canary** and **Insider** channels, users are _always_ required to update to the latest version if an update exists.
+- In the **Production** channel, users are _generally_ allowed to use either of the 2 most recent **Production** releases. Once a third **Production** release is available, users will be required to update to the most recent version.
+- There are _occasional_ cases where a **Production** release is required. This is done to ensure that all users are running a version that is supported by the Accessibility Insights for Windows team. This is done in the following cases:
+  - A security vulnerability is discovered in a previous version (and fixed in the most recent version).
+  - A critical bug is discovered in a previous version (and fixed in the most recent version).
+
+To generate a Production release that creates a mandatory upgrade, run the build pipeline with the `IsMandatoryProdUpdate` variable set to `true`. This variable defaults to 'false' in the build pipeline and can be overridden when manually running a signed build.
+
 ### Changing channels
 This scenario occurs after the user changes the release channel from the Settings tab. The application does the following:
 - It makes a web call to retrieve the update manifest for the newly selected release channel.

src/ManifestTests/IntegrationTests.cs

@@ -7,7 +7,6 @@ using Microsoft.VisualStudio.TestTools.UnitTesting;
 using System;
 using System.Collections.Generic;
 using System.IO;
-using System.Linq;
 
 namespace ManifestTests
 {
@@ -77,6 +76,20 @@ namespace ManifestTests
                 Assert.AreEqual(rawInfo.CurrentVersion, signedInfo.CurrentVersion);
                 Assert.AreEqual(rawInfo.ProductionMinimumVersion, signedInfo.ProductionMinimumVersion);
                 Assert.AreEqual(rawInfo.MinimumVersion, signedInfo.MinimumVersion);
+
+                string isMandatoryProdUpdate = Environment.GetEnvironmentVariable("IsMandatoryProdUpdate");
+
+                if (isMandatoryProdUpdate == "true")
+                {
+                    Assert.AreEqual(rawInfo.CurrentVersion, rawInfo.ProductionMinimumVersion);
+                }
+                else
+                {
+                    Assert.IsTrue(string.IsNullOrEmpty(isMandatoryProdUpdate) || isMandatoryProdUpdate == "false",
+                        "The IsMandatoryProdUpdate environment variable must be 'true' or 'false' (case sensitive) if it is set.");
+                    Assert.IsTrue(rawInfo.CurrentVersion > rawInfo.ProductionMinimumVersion,
+                        "This is not a mandatory prod update. CurrentVersion must be newer than ProductionMininmumVersion");
+                }
             }
         }
 

tools/scripts/create-json-for-manifest.ps1

@@ -137,7 +137,7 @@ function CreateJsonForManifest([string]$msiBasePath, [string]$octokitRelativePat
     $info.installer_url = "https://www.github.com/Microsoft/accessibility-insights-windows/releases/download/v$paddedVersion/$MsiName"
     $info.release_notes_url = "https://www.github.com/Microsoft/accessibility-insights-windows/releases/tag/v$paddedVersion"
     $info.current_version = $paddedVersion
-    $info.production_minimum_version = Get-MinimumProductionVersion $paddedVersion $octokitRelativePath $IsMandatoryProdUpdate
+    $info.production_minimum_version = Get-MinimumProductionVersion $paddedVersion $octokitRelativePath $isMandatoryProdUpdate
 
     $json = $info | ConvertTo-Json
 
@@ -165,6 +165,6 @@ function CreateOutputFile([string]$json, [string]$outputPath, [string]$outputFil
 }
 
 $resolvedOutputPath = Resolve-Path $OutputPath
-$json = CreateJsonForManifest $MsiBasePath $OctokitRelativePath $isMandatoryProdUpdate
+$json = CreateJsonForManifest $MsiBasePath $OctokitRelativePath $IsMandatoryProdUpdate
 CreateOutputFile $json $resolvedOutputPath $OutputFile
 exit 0