MSBuild Release Checklist 18.6

[MichalPavlik]

Inputs

Placeholder	Description	Value
PREVIOUS_RELEASE_VERSION	Version being replaced as latest	18.5
THIS_RELEASE_VERSION	Version being released now	18.6
THIS_RELEASE_EXACT_VERSION	Full VersionPrefix on release branch after final branding	18.6.0
NEXT_VERSION	Version that main will be bumped to	18.7

Derived values:

• Release branch: vs18.6
• DARC channel: VS 18.6
• Next DARC channel: VS 18.7
• VS insertion target: VS main (VS snaps main → insiders → stable on its own schedule)

Phase 0: Instantiate Release

Trigger: User decides to start a release. Do this first.

• Validate inputs:
  • Confirm eng/Versions.props on main has VersionPrefix = 18.6.0
  • Confirm branch vs18.6 does not already exist
  • Confirm DARC channel VS 18.6 exists (ID: 8708)
• Create this tracking issue in dotnet/msbuild with all placeholders replaced
• Record all tracking URLs in the table below as phases are completed:

Artifact	URL
Next-version branding PR
VisualStudio.ChannelName PR
Phase 1 DARC config PR
Phase 3 DARC config PR
Final branding PR
VS insertion PR
Channel promotion PR

---

Phase 1: Branch & Prepare

Trigger: 2026-04-03 reached.

Steps are sequential — complete in order.

• 1.1 Create branch vs18.6 from HEAD of main:
  git push upstream HEAD:refs/heads/vs18.6
  • If branched too early (main has commits that shouldn't be in the release): fast-forward the branch to the correct commit (the one currently inserted into VS main):
    git push upstream <correct_sha>:refs/heads/vs18.6
• 1.2 DARC configuration — batch all channel/mapping changes into one PR on the maestro-configuration repo.
  Use --configuration-branch release/msbuild-18.6 on every command and --no-pr on all but the last:
  • 1.2a Ensure branch-to-channel association exists:
    First check: darc get-default-channels --channel "VS 18.6" --branch vs18.6 --source-repo https://github.com/dotnet/msbuild
    If No matching channels were found.:
    darc add-default-channel --channel "VS 18.6" --branch vs18.6 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.6 --no-pr
  • 1.2b Create DARC channel for next release:
    darc add-channel --name "VS 18.7" --configuration-branch release/msbuild-18.6 --no-pr
    (Channel VS 18.7 already exists — ID 10189, so this is a no-op.)
  • 1.2c Pre-create default channel mapping for the next release branch (last command — omit --no-pr to create the PR):
    darc add-default-channel --channel "VS 18.7" --branch vs18.7 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.6
  • 1.2d Get the maestro-configuration PR reviewed and merged
  • 1.2e Ping internal "First Responders" Teams channel to get the new VS 18.7 channel available as a promotion target
• 1.3 Update .config/git-merge-flow-config.jsonc:
  Insert vs18.6 as the last entry before main in the merge chain. Add a comment noting the VS/SDK version context.

---

Phase 2: Bump Main & Update Pipelines

Trigger: vs18.6 branch exists (Phase 1.1 done). Previous release is in insiders stage.

Create one PR in main containing all of the following changes:

• 2.1 eng/Versions.props: Update VersionPrefix to 18.7.0
• 2.2 eng/Versions.props: Update PackageValidationBaselineVersion to the last released version (the 18.5 GA version published to nuget.org).
• 2.3 If needed, update CompatibilitySuppressions.xml files. Run:
  dotnet pack MSBuild.Dev.slnf /p:ApiCompatGenerateSuppressionFile=true
  See API compat documentation for details.
• 2.4 Update azure-pipelines/vs-insertion.yml: set AutoInsertTargetBranch for vs18.6 → VS main.
• 2.5 Update azure-pipelines/vs-insertion-experimental.yml:
  Add rel/insiders and/or rel/stable to TargetBranch parameter values if not already present.
• 2.6 Merge branding PR

---

Phase 3: DARC Subscription Updates

Trigger: Phase 2 branding PR merged (main now has 18.7 version).

First, gather information (read-only queries — no PR needed):

• 3.1 Find the SDK main subscription ID to update:
  darc get-subscriptions --exact --source-repo https://github.com/dotnet/msbuild --channel "VS 18.6"
  Note the subscription ID for the SDK main branch entry.
• 3.2 Verify release branch channel association:
  darc get-default-channels --source-repo https://github.com/dotnet/msbuild --branch vs18.6
  Note whether the association exists (needed for step 3.3d).

Then, batch all write operations into one PR on the maestro-configuration repo.
Use --configuration-branch release/msbuild-18.6-main-bump and --no-pr on all but the last command:

• 3.3 DARC channel/subscription updates:
  • 3.3a Remove main → old channel mapping:
    darc delete-default-channel --repo https://github.com/dotnet/msbuild --branch main --channel "VS 18.6" --configuration-branch release/msbuild-18.6-main-bump --no-pr
  • 3.3b Associate main with next channel:
    darc add-default-channel --channel "VS 18.7" --branch main --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.6-main-bump --no-pr
  • 3.3c Update SDK main subscription to new channel:
    darc update-subscription --id <subscription_id_from_3.1> --channel "VS 18.7" --configuration-branch release/msbuild-18.6-main-bump --no-pr
  • 3.3d If release branch association was missing in 3.2, add it:
    darc add-default-channel --channel "VS 18.6" --branch vs18.6 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.6-main-bump --no-pr
  • 3.3e If any subscriptions need fixing (from 3.4–3.6 below), include them here with --no-pr.
  • 3.3f Create the PR — re-run step 3.3b (or whichever was the last write command executed) without --no-pr to open the PR on the configuration branch.
  • 3.3g Get the maestro-configuration PR reviewed and merged

Verifications (parallel — read-only, no ordering dependency):

• 3.4 Verify Arcade subscription:
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/arcade
• 3.5 Verify NuGet client subscription:
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/nuget/nuget.client
• 3.6 Verify Roslyn subscription:
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/roslyn
• 3.7 Confirm Roslyn and NuGet subscriptions are disabled (Enabled: False)
• 3.8 Fix any missing or misconfigured subscriptions

---

Phase 4: Final Branding & VS Insertion

Trigger: 7 calendar days before 2026-04-03 (i.e., ~2026-03-27).
Precondition: Phases 1–3 complete. Preview builds from vs18.6 have been inserting into VS main since Phase 2.
Goal: Final-brand the release branch and get the final-branded bits inserted into VS main before VS snaps to rel/insiders.

Steps are sequential.

• 4.1 Promote public API on vs18.6 branch:
  Move contents of PublicAPI.Unshipped.txt → PublicAPI.Shipped.txt for all projects with API changes.
• 4.2 Run scripts/Stabilize-Release.ps1 on vs18.6 branch:
  Use -DryRun first to preview.
• 4.3 Create and merge final branding PR to vs18.6
• 4.4 Bootstrap OptProf for vs18.6:
  • Run the official build for vs18.6 with Optional OptProfDrop Override set to main's latest OptProf drop path, or set SkipApplyOptimizationData to true.
  • Verify that the OptProf data collection pipeline triggers for vs18.6.
  • Run the official build for vs18.6 with no overrides.
• 4.5 Get M2 or QB approval as necessary per the VS schedule
• 4.6 Babysit the VS insertion PR from vs18.6 into VS main. Final-branded bits must be in VS main before 2026-04-03.
• 4.7 (After insiders snap, if needed) Retarget AutoInsertTargetBranch for vs18.6 from VS main → rel/insiders.
• 4.8 (After stable snap, if needed) Retarget AutoInsertTargetBranch for vs18.6 → rel/stable.

---

Phase 5: Post-GA

Trigger: 2026-05-12 has passed and VS release has shipped.

• 5.1 Push packages to nuget.org (contact dnceng). Packages:
  • Microsoft.Build.Utilities.Core.18.6.0.nupkg
  • Microsoft.Build.18.6.0.nupkg
  • Microsoft.Build.Framework.18.6.0.nupkg
  • Microsoft.Build.Runtime.18.6.0.nupkg
  • Microsoft.Build.Tasks.Core.18.6.0.nupkg
  • Microsoft.NET.StringTools.18.6.0.nupkg
  • Microsoft.Build.Templates.18.6.0.nupkg
• 5.2 Publish docs at https://aka.ms/publishondocs
• 5.3 Create GitHub release:

  git checkout <final-branding commit on vs18.6>
  git tag v18.6.0
  git push upstream v18.6.0
  

  Create release at https://github.com/dotnet/msbuild/releases/new
• 5.4 Update BootstrapSdkVersion in eng/Versions.props if a fresh SDK was released.
• 5.5 Extend OptProf data expiration for vs18.6 branch if the release is LTSC.
• 5.6 Verify main subscriptions point to VS 18.7 channel:
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --target-branch main
• 5.7 Review this tracking issue for any process deviations.

[MichalPavlik]

Phase 2 branding PR: #13472

[MichalPavlik]

Phase 4 final branding PR: #13473

[rainersigwald]

Phase 3: DARC Subscription Updates

Trigger: Phase 2 branding PR merged (main now has 18.7 version).

This is wrong, the the darc stuff must be done BEFORE almost everything else.