Release 17.14

[JanProvaznik]

MSBuild Release Checklist 17.14

At any time

• Create a new issue to track the release checklist, with this checklist copied into the issue.
  • Replace 17.13 with the previous release version, for example 17.9
  • Replace 17.14 with the current release version, for example 17.10
  • Replace 18.0 with the next release version, for example 17.11
• Create vs17.14 branch
• Create darc channel for VS 18.0 if it doesn't already exist
  darc add-channel --name "VS 18.0"
• 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): {{URL_OF_CHANNEL_PROMOTION_PR}}

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.0 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 vs17.14 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 vs17.14 to VS main. Keep scheduled daily insertions to simplify your workflow and exclude vs17.14 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 17.14" --branch vs17.14 --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 vs17.14 branch with the next VS 17.14 release channel
        darc add-default-channel --channel "VS 17.14" --branch vs17.14 --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 vs17.14 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.0 branding PR (in main) including public API baseline package version change: {{URL_OF_NEXT_VERSION_BRANDING_PR}}.
  • In the file eng/Versions.props Update the VersionPrefix to 18.0 and PackageValidationBaselineVersion set to a latest internally available 17.14 preview version in the internal 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 17.14 and updates its version to 18.0, 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 vs17.14 to the corresponding VS branch rel/d17.14.
      • Add a selection rule for vs18.0 -> rel/d18.0 (preparation if we need to branch early and backport to previews)
    • Add rel/d17.14 case to TargetBranch parameter in Experimental insertion
    • Set scheduled insertion for main and remove exclusion of vs17.14 triggering on each commit if added earlier.
• Merge 18.0 branding PR

Adjust DARC channels and subscriptions

• Remove the main to old release channel (17.14) default channel
  darc delete-default-channel --repo https://github.com/dotnet/msbuild --branch main --channel "VS 17.14"
• Associate the main branch with the next release channel
  darc add-default-channel --channel "VS 18.0" --branch main --repo https://github.com/dotnet/msbuild
• Prepare the same channel association as well for the next release branch (vs18.0) - as a preparation for a next release:
  darc add-default-channel --channel "VS 18.0" --branch vs18.0 --repo https://github.com/dotnet/msbuild
• Check subscriptions for the forward-looking channel VS 18.0 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 17.14"
  • Update channel VS 17.14 to VS 18.0 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.0"
• Ensure that the current release channel VS 17.14 is associated with the correct release branch
  darc get-default-channels --source-repo https://github.com/dotnet/msbuild --branch vs17.14
  if it is not, darc add-default-channel --channel "VS 17.14" --branch vs17.14 --repo https://github.com/dotnet/msbuild
• Double check subscriptions from our repo darc get-subscriptions --target-repo dotnet/msbuild and update subscriptions to VS17.14 and main branches 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
  • Source Build Packages
    • Based on .NET version channel
    • darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/source-build-reference-packages
  • 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 vs17.14 branch
  • Run the official build for vs17.14 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 vs17.14. If not, run manually ('Run pipeline' in upper right)
  • Run the official build for vs17.14 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 17.14 localization ticket: https://aka.ms/ceChangeLocConfig (requesting to switch localization from 17.13 to 17.14): {{URL_OF_LOCALIZATION_TICKET}}
• Enable 17.14 localization - by setting EnableReleaseOneLocBuild to true
• Disable 17.13 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 vs17.14: {{URL_OF_FINAL_BRANDING_PR}}
  Edit Version.props file - add <DotNetFinalVersionKind>release</DotNetFinalVersionKind> as a suffix (on same line! - to intentionaly make it merge conflict on flows to main) after the VersionPrefix
  e.g.: Final Branding #11130, Add final branding VS17.12 #10697
• Merge final branding to vs17.14 branch
• Update perfstar MSBuild insertions configuration: example PR: {{URL_OF_PERFSTAR_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): {{URL_OF_VS_INSERTION}}
  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 (17.14.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): {{URL_OF_PR}}

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.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.Build.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.Build.Framework.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.Build.Runtime.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.Build.Tasks.Core.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.NET.StringTools.{{THIS_RELEASE_EXACT_VERSION}}.nupkg
  • Microsoft.Build.Templates.{{THIS_RELEASE_EXACT_VERSION}}.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: submit reference request at https://aka.ms/publishondocs

  • Click on the link labeled Request – Reference Publishing
  • 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 17.14 - channle start to publish in the next - VS 18.0 - channel)
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --target-branch main

• Create the 17.14 release

  • Create tag (can be done upfront)

  git checkout <commit noted above>
  git tag v17.14.3
  git push upstream v17.14.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)