Release 18.5

[MichalPavlik]

MSBuild Release Checklist 18.5

At any time

• Create a new issue to track the release checklist, with this checklist copied into the issue.
  • Replace 18.4 with the previous release version, for example 17.9
  • Replace 18.5 with the current release version, for example 17.10
  • Replace 18.6 with the next release version, for example 17.11
• Create vs18.5 branch
• Create darc channel for VS 18.6 if it doesn't already exist
  darc add-channel --name "VS 18.6"
• Ping internal "First Responders" Teams channel to get the new channel made available as a promotion target (e.g. Make "VS 17.6" darc channel promotionable arcade#12150):

At release time

Before starting the process:

• If the release is being cut more than a few days before the VS-side snap, run insertions manually OR redirect MSBuild release branch
  • Disable scheduled run of MSBuild VS Insertion pipeline (our 18.6 builds don't have a place to go in VS yet) by: Edit -> ... -> Triggers -> add a schedule on a dead branch (this overrides the YAML defined once-per-day schedule for main). Manual pipeline run: select as input resource the to-be-inserted "MSBuild" pipeline run on branch vs18.5 and VS TargetBranch main.
    OR
  • If the release is being cut more than couple of weeks modify YAML (and merge to affected MSBuild branches) of the VS insertion pipeline so that it schedules insertions from MSBuild vs18.5 to VS main. Keep scheduled daily insertions to simplify your workflow and exclude vs18.5 from triggering insertion on each commit.

Branching from main

• Ensure planned branch association to the channel
  • Check if the association exist (it is now recommended to create it as a part of the previous release checklist):
    darc get-default-channels --channel "VS 18.5" --branch vs18.5 --source-repo https://github.com/dotnet/msbuild
    • This step is done if output shows active expected association such as:
      (5997) https://github.com/dotnet/msbuild @ vs17.13 -> VS 17.13
    • If the association is missing - we'll see output similar to:
      No matching channels were found.
      • In such case - associate the vs18.5 branch with the next VS 18.5 release channel
        darc add-default-channel --channel "VS 18.5" --branch vs18.5 --repo https://github.com/dotnet/msbuild
• If the new version's branch was created before the Visual Studio fork: fast-forward merge the correct commit (the one that is currently inserted to VS main) to the vs18.5 branch
  e.g.: git push upstream 2e6f2ff7ea311214255b6b2ca5cc0554fba1b345:refs/heads/vs17.10
  (This is for the case where we create the branch too early and want it to be based actually on a different commit. If you waited until a good point in time with main in a clean state, just branch off and you are done. The branch should point to a good, recent spot, so the final-branding PR goes in on top of the right set of commits.)
• Update the branch merge flow in .config/git-merge-flow-config.jsonc file to have the currently-in-servicing branches.
• Create 18.6 branding PR (in main) including public API baseline package version change: .
  • In the file eng/Versions.props Update the VersionPrefix to 18.6 and PackageValidationBaselineVersion set to a latest internally available 18.5 preview version in the public dnceng dotnet-tools feed. It might be needed to update CompatibilitySuppressions.xml files. See this documentation for more details. You can update CompatibilitySuppressions.xml files by running
    dotnet pack MSBuild.Dev.slnf /p:ApiCompatGenerateSuppressionFile=true.
  • When VS main snaps to 18.5 and updates its version to 18.6, modify the MSBuild VS Insertion pipeline YAML so that it flows from MSBuild main to VS main.
    • Update AutoTargetBranch selection in the YAML (add to parameters and make new AutoTargetBranch rule by copying it from existing ones) of the MSBuild VS Insertion pipeline to insert MSBuild vs18.5 to the corresponding VS branch rel/d18.5.
      • Add a selection rule for vs18.6 -> rel/d18.6 (preparation if we need to branch early and backport to previews)
    • Add rel/d18.5 case to TargetBranch parameter in Experimental insertion
    • Set scheduled insertion for main and remove exclusion of vs18.5 triggering on each commit if added earlier.
• Merge 18.6 branding PR

Adjust DARC channels and subscriptions

• Remove the main to old release channel (18.5) default channel
  darc delete-default-channel --repo https://github.com/dotnet/msbuild --branch main --channel "VS 18.5"
• Associate the main branch with the next release channel
  darc add-default-channel --channel "VS 18.6" --branch main --repo https://github.com/dotnet/msbuild
• Prepare the same channel association as well for the next release branch (vs18.6) - as a preparation for a next release:
  darc add-default-channel --channel "VS 18.6" --branch vs18.6 --repo https://github.com/dotnet/msbuild
• Check subscriptions for the forward-looking channel VS 18.6 and update as necessary (for instance, SDK's main branch should usually be updated, whereas release branches often should not be
  darc get-subscriptions --exact --source-repo https://github.com/dotnet/msbuild --channel "VS 18.5"
  • Update channel VS 18.5 to VS 18.6 for the sdk main subscription and any others from the previous step
    darc update-subscription --id <subscription_id_of_msbuild_main_to_sdk_main> --channel "VS 18.6"
• Ensure that the current release channel VS 18.5 is associated with the correct release branch
  darc get-default-channels --source-repo https://github.com/dotnet/msbuild --branch vs18.5
  if it is not, darc add-default-channel --channel "VS 18.5" --branch vs18.5 --repo https://github.com/dotnet/msbuild
• Double check subscriptions from our repo darc get-subscriptions --target-repo dotnet/msbuild and update subscriptions to VS18.5 branch according to supported versions of VS and SDK:
  • Arcade:
    • Based on .NET version channel--does not change every MSBuild release
    • darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/arcade
• Double check subscriptions from our repo darc get-subscriptions --target-repo dotnet/msbuild and update subscriptions to main branch according to supported versions of VS and SDK:
  • NuGet client
    • Based on VS version channel
    • darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/nuget/nuget.client
  • Roslyn:
    • Based on VS version channel
    • darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/roslyn
  • Arcade:
    • Based on .NET version channel--does not change every MSBuild release
    • darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/arcade
• Make sure the non-infrastructure dependencies (currently Roslyn and Nuget) are set to 'disabled' ( - Enabled: False in the darc get-subscriptions output) - we do not want to automatically bump them. The version updates should be explicitly driven by SDK or VS.
• Any missing subscription need to be added via darc add-subscription command, any misconfigured subscription needs to be edit via darc update-subscription command (for additional required and optional parameters run with --help)

Adjust pipelines / releases

• Fix OptProf data flow for the new vs18.5 branch
  • Run the official build for vs18.5 without OptProf (set SkipApplyOptimizationData variable in 'Advanced options' section of the 'Run pipeline' menu to true) or alternatively with the latest Opt-Prof collected for the main branch (set Optional OptProfDrop Override to the drop path of the collected data, which could be found in the logs of the pipeline: Windows_NT -> Build -> search for OptimizationData).
  • Check that the OptProf data collection pipeline run is triggered for vs18.5. If not, run manually ('Run pipeline' in upper right)
  • Run the official build for vs18.5 with no extra customization - OptProf should succeed now
• Restore MSBuild VS Insertion pipeline to the default YAML defined schedule, by removing all triggers from Edit -> ... -> Triggers.

Configure localization

• Create 18.5 localization ticket: https://aka.ms/ceChangeLocConfig (requesting to switch localization from 18.4 to 18.5): https://ceapex.visualstudio.com/CEINTL/_workitems/edit/1127015/
• Enable 18.5 localization - by setting EnableReleaseOneLocBuild to true
• Disable 18.4 localization - by setting EnableReleaseOneLocBuild to false. Update the comment on the same line.
• Create and merge a PR in main to update a localization version comment in setting EnableReleaseOneLocBuild to set up the merge conflict when this line will be updated in the release branch.

Final branding

• Prepare final branding PR for vs18.5:
  Use scripts\Stabilize-Release.ps1 script to update eng\Versions.props properties.
• Merge final branding to vs18.5 branch
• Update perfstar MSBuild insertions configuration: example PR:
• Get M2 or QB approval as necessary per the VS schedule
• Merge to VS (babysit the automatically generated VS insertion PR https://devdiv.visualstudio.com/DevDiv/_git/VS/pullrequests for the MSBuild commit noted in above step):
  The PR will be helpful for requesting nuget packages publishing - as it contains the inserted packages versions
  • Respond to the 'VS xyz package stabilization' email - with the merged insertion PR (as nowVS is on stable version).
• Update the PackageValidationBaselineVersion to the latest released version (18.5.0) - this might require temporary addition of the build artifacts feed as the new version is not yet added to the official feeds (this is post release). This can trigger a high severity CG error (https://eng.ms/docs/cloud-ai-platform/devdiv/one-engineering-system-1es/1es-docs/secure-supply-chain/how-to-securely-configure-package-source-files) - however it should be fine to keep this temporary feed untill the release.
• Update the requested SDK version for bootstrap folder (the BootstrapSdkVersion property in Versions.props) if a fresh sdk was released (released runtimes and associated sdk versions can be checked here - https://dotnet.microsoft.com/download/visual-studio-sdks - make sure to always check the details of the appropriate targeted version of .NET for the matching latest version of SDK).
• Update VisualStudio.ChannelName (and VisualStudio.MajorVersion if applicable) of Windows_NT build step for our build pipeline in a newly created branch - it should point to the matching VS release branch and make sure the change is not automatically mergable with the interbranch flow (example: [vs17.8] Select proper VS channel #11246):

ASAP On/After GA:

Timing based on the (Microsoft-internal) release schedule.

• Push packages to nuget.org (not currently automated, contact dnceng - search "Publish MSBuild 17.6 to NuGet.org" email subject for template).

  Following packages should be published (THIS_RELEASE_EXACT_VERSION is equal to VersionPrefix that comes form the eng\Version.props, that were part of the build we are trying to get published, it is as well part of the VS insertion PR noted above):

  • Microsoft.Build.Utilities.Core.18.5.0.nupkg
  • Microsoft.Build.18.5.0.nupkg
  • Microsoft.Build.Framework.18.5.0.nupkg
  • Microsoft.Build.Runtime.18.5.0.nupkg
  • Microsoft.Build.Tasks.Core.18.5.0.nupkg
  • Microsoft.NET.StringTools.18.5.0.nupkg
  • Microsoft.Build.Templates.18.5.0.nupkg

  Note: Microsoft.Build.Conversion.Core and Microsoft.Build.Engine are not part of the list. Microsoft.Build.Templates is part of the list. Those 3 packages are a difference to the historic publishing list.

• Publish docs: Create ticket with existing template

  • You can use existing ticket as a reference

• Remove the temporarily added build feed from nuget.config if it was added in the Update the PackageValidationBaselineVersion step

• Update main subscriptions to the new channel (this can be done before or after release - depending on when the source repos from our previous - VS 18.5 - channle start to publish in the next - VS 18.6 - channel)
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --target-branch main

• Create the 18.5 release

  • Create tag (can be done upfront)

  git checkout <commit noted above>
  git tag v18.5.3
  git push upstream v18.5.3
  

  • Create Release in Github with Create Release from Tag GH option (https://github.com/dotnet/msbuild/releases/new?tag=v17.9.3) - the release notes can be prepopulated (Generate Release Notes)

• Extend the expiration date of the latest Opt-Prof data for vs18.5 branch.

  • Identify the location of the latest Opt-Prof data in VS Drop. The path should follow the format OptimizationData/DotNet-msbuild-Trusted/vs18.5/.... It can be found in the MSBuild CI logs of the "Build" task or alternatively, in the Opt-Prof pipeline logs under the "Publish OptimizationInputs drop" task.
  • Get drop.exe CLI tool.
  • Use this instruction to set the new expiration to (End of support date for the corresponding Visual Studio version) plus 3 months.

After release

If v18.6 is a new major version

• do Major version extra update steps from release.md