MSBuild Release Checklist 18.8

[OvesN]

MSBuild Release Checklist 18.8

Inputs

Fill in these values before starting. Version increments are irregular — they must be specified explicitly.

Placeholder	Description	Value
{{PREVIOUS_RELEASE_VERSION}}	Version being replaced as latest (e.g. 18.5)	18.7
{{THIS_RELEASE_VERSION}}	Version being released now (e.g. 18.6)	18.8
{{THIS_RELEASE_EXACT_VERSION}}	Full VersionPrefix from eng/Versions.props on the release branch after final branding (e.g. 18.6.0). For non-patch releases this is always {{THIS_RELEASE_VERSION}}.0.	18.8.0
{{NEXT_VERSION}}	Version that main will be bumped to (e.g. 18.7)	18.9
{{BRANCH_SNAP_DATE}}	Date MSBuild branches vs* from main. Insertion targets VS main.	2026-05-27
{{INSIDERS_SNAP_DATE}}	Date VS snaps main → rel/insiders. Final-branded MSBuild must be in VS main before this date. From VS-Dates wiki	2026-05-29
{{STABLE_SNAP_DATE}}	Date VS snaps rel/insiders → rel/stable. From VS-Dates wiki	2026-06-23
{{VS_SHIP_DATE}}	Date VS ships publicly (GA). Post-GA tasks (nuget.org, docs) happen after this.	2026-07-14

Derived values (do not edit — computed from inputs):

• Release branch: vs18.8
• DARC channel: VS 18.8
• Next DARC channel: VS 18.9
• 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.8.0 — if not, the inputs are wrong
  • Confirm branch vs18.8 does not already exist — if it does, this release was already started
  • Confirm DARC channel VS 18.8 exists:
    darc get-channel --name "VS 18.8"
    If missing, it should have been created during the previous release (Phase 1.2b "create next channel" step). Create it now: darc add-channel --name "VS 18.8"
• 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	#13880
VisualStudio.ChannelName PR	{{URL_OF_CHANNEL_NAME_PR}}
Phase 1 DARC config PR	https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/61536
Phase 3 DARC config PR	https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/61538
Final branding PR	#13883
VS insertion PR	https://dev.azure.com/devdiv/DevDiv/_git/VS/pullrequest/742873

---

Phase 1: Branch & Prepare

Trigger: 2026-05-27 reached.

Steps are sequential — complete in order.

• 1.1 Create branch vs18.8 from HEAD of main:
  git push upstream HEAD:refs/heads/vs18.8
  • 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.8
• 1.2 DARC configuration — batch all channel/mapping changes into one PR on the maestro-configuration repo.
  Use --configuration-branch release/msbuild-18.8 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.8" --branch vs18.8 --source-repo https://github.com/dotnet/msbuild
    If No matching channels were found.:
    darc add-default-channel --channel "VS 18.8" --branch vs18.8 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.8 --no-pr
  • 1.2b Create DARC channel for next release:
    darc add-channel --name "VS 18.9" --configuration-branch release/msbuild-18.8 --no-pr
    (If channel already exists, 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.9" --branch vs18.9 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.8
  • 1.2d Get the maestro-configuration PR reviewed and merged: https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/61536
• 1.3 Update .config/git-merge-flow-config.jsonc:
  Insert vs18.8 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.8 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.9.0
• 2.2 eng/Versions.props: Update PackageValidationBaselineVersion to the last released version (the 18.7 GA version published to nuget.org).
• 2.3 Not needed - update CompatibilitySuppressions.xml files. Run:
  dotnet pack MSBuild.Dev.slnf /p:ApiCompatGenerateSuppressionFile=true
  See API compat documentation for details.
• 2.4 Not needed - Update azure-pipelines/vs-insertion.yml: set AutoInsertTargetBranch for vs18.8 → VS main.
• 2.5 Not needed - 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: Bump main to 18.9.0 after vs18.8 snap #13880

---

Phase 3: DARC Subscription Updates

Trigger: Phase 2 branding PR merged (main now has 18.9 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.8"
  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.8
  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.8-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.8" --configuration-branch release/msbuild-18.8-main-bump --no-pr
  • 3.3b Associate main with next channel:
    darc add-default-channel --channel "VS 18.9" --branch main --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.8-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.9" --configuration-branch release/msbuild-18.8-main-bump --no-pr
  • 3.3d If release branch association was missing in 3.2, add it:
    darc add-default-channel --channel "VS 18.8" --branch vs18.8 --repo https://github.com/dotnet/msbuild --configuration-branch release/msbuild-18.8-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: https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/61538

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

• 3.4 Verify Arcade subscription (based on .NET version channel — rarely changes):
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/arcade
• 3.5 Verify NuGet client subscription (based on VS version channel):
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/nuget/nuget.client
• 3.6 Verify Roslyn subscription (based on VS version channel):
  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 in output). We do not want to automatically bump them — version updates are driven by SDK or VS.
• 3.8 Fix any missing or misconfigured subscriptions by adding write commands to the Phase 3 PR branch (step 3.3e) before merging, or with a separate darc add-subscription / darc update-subscription (run with --help for params)

---

Phase 4: Final Branding & VS Insertion

Trigger: 7 calendar days before 2026-05-29.
Precondition: Phases 1–3 complete. Preview builds from vs18.8 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.8 branch:
  Move contents of PublicAPI.Unshipped.txt → PublicAPI.Shipped.txt for all projects with API changes. See release.md for details.
• 4.2 Run scripts/Stabilize-Release.ps1 on vs18.8 branch:
  Use -DryRun first to preview. The script adds <DotNetFinalVersionKind>release</DotNetFinalVersionKind> on the same line as VersionPrefix (creates merge conflict for forward-flow) and changes PreReleaseVersionLabel from preview to servicing.
  If the script says "already stabilized" — skip (idempotent).
• 4.3 Create and merge final branding PR to vs18.8: Stable branding for 18.8 release #13883
• 4.4 Bootstrap OptProf for vs18.8:
  • Run the official build for vs18.8 with Optional OptProfDrop Override set to main's latest OptProf drop path. (Find the path in main CI logs: Windows_NT → Build → search for OptimizationData.) Alternatively, set SkipApplyOptimizationData to true in Advanced options.
  • Verify that the OptProf data collection pipeline triggers for vs18.8. If not triggered, run manually ('Run pipeline' in upper right).
  • Run the official build for vs18.8 with no overrides — OptProf should succeed now.
• 4.5 Get M2 or QB approval as necessary per the VS schedule
• 4.6 Babysit the VS insertion PR from vs18.8 into VS main (auto-generated at https://devdiv.visualstudio.com/DevDiv/_git/VS/pullrequests). The final-branded bits must be in VS main before 29.5 so they are included when VS snaps to rel/insiders: https://dev.azure.com/devdiv/DevDiv/_git/VS/pullrequest/742873\
  The insertion PR contains the inserted package versions — useful for the nuget.org publishing step.

After insiders snap (only if a backport to insiders is needed):

• 4.7 Update azure-pipelines/vs-insertion.yml: retarget AutoInsertTargetBranch for vs18.8 from VS main → rel/insiders. This enables direct insertion of hotfix commits into the insiders branch.

After stable snap (only if a backport to stable is needed):

• 4.8 Update azure-pipelines/vs-insertion.yml: retarget AutoInsertTargetBranch for vs18.8 → rel/stable. This enables direct insertion of hotfix commits into the stable branch.

---

Phase 5: Post-GA

Trigger: 2026-07-14 has passed and VS release has shipped.

Steps are mostly parallel unless noted.

• 5.1 Push packages to nuget.org. Contact dnceng — search "Publish MSBuild 18.8 to NuGet.org" email subject for template.
  THIS_RELEASE_EXACT_VERSION = VersionPrefix from eng/Versions.props on the release branch (also visible in the VS insertion PR). Packages to publish taken from the official build https://devdiv.visualstudio.com/DevDiv/_build?definitionId=9434 for the 18.8 branch; search in artifacts under the Shipping folder for:

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

• 5.2 Publish docs: submit reference request at https://aka.ms/publishondocs
  Click Request – Reference Publishing. Use existing ticket as a reference.

• 5.3 Create GitHub release:

  git checkout <final-branding commit on vs18.8>
  git tag v18.8.0
  git push upstream v18.8.0
  

  Create release at https://github.com/dotnet/msbuild/releases/new — use Generate Release Notes to prepopulate.

• 5.4 Update BootstrapSdkVersion in eng/Versions.props if a fresh SDK was released. Check https://dotnet.microsoft.com/download/visual-studio-sdks — always verify the details for the targeted .NET version.

• 5.5 Extend OptProf data expiration for vs18.8 branch if the release is LTSC:

  • Find the drop at OptimizationData/DotNet-msbuild-Trusted/vs18.8/... (in MSBuild CI logs: Build task, or OptProf pipeline: "Publish OptimizationInputs drop" task)
  • Get drop.exe CLI
  • Set expiration to VS support end date + 3 months per these instructions

• 5.6 Verify main subscriptions point to VS 18.9 channel (should have been done in Phase 3; confirm):
  darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --target-branch main

• 5.7 Review this tracking issue for any process deviations. If the process changed, create a PR to update documentation/release-checklist.md with the improvements.

---

If 18.9 is a new major version

18.9 is not a new major version (still 18.x). This section can be ignored for this release.

• Update VS major version references per release.md:
  • src/Shared/BuildEnvironmentHelper.cs
  • src/Shared/Constants.cs
  • src/Framework/Telemetry/TelemetryConstants.cs