Skip to content

MSBuild Release Checklist 18.7 #13639

Closed
Closed
MSBuild Release Checklist 18.7#13639
Assignees
JanProvaznikAlesProkop
@SimaTian

Description

@SimaTian
SimaTian
opened on Apr 28, 2026

MSBuild Release Checklist 18.7

Release Output

Artifacts produced over the course of the release. Record each URL here as the corresponding phase completes so this issue serves as the single index back into every PR / build / tag that defines 18.7.1 (the version that shipped to customers; the template originally assumed 18.7.0).

Artifact URL
Phase 1.2d — maestro-configuration PR (channels for 18.7 / 18.8) https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/60575
Phase 2.3h — maestro-configuration PR(s) (main subscriptions retargeted to VS 18.8) Three PRs (darc auto-created one per write): #60704, #60705, #60706
Phase 3.4 — main next-version main-bump PR dotnet/msbuild#13657 — OPEN, BLOCKED on broken-on-main test Microsoft.Build.Utilities.UnitTests_net472_x86
Phase 4.3 — vs18.7 final branding PR dotnet/msbuild#13658 (merged 2026-04-30 12:27 UTC, commit 6ed5e9aa)
Phase 4.6 — VS insertion PR devdiv VS#734106 (merged 2026-05-01 01:58 UTC, 18.7.1-servicing-26230-11 → VS main before insiders snap)
Phase 5.3 — GitHub release tag v18.7.1 — tagged at commit 024f5b03 (the GA build's source). Note: shipped version is 18.7.1, not 18.7.0 — see Phase 5.1 below.
Phase 5.2a — reference-publishing ticket msft-skilling/Content #586884 — cloned from the 18.6 ticket (#578189), updated to 18.7
Phase 5.2c — change-waves Learn page Already in sync for 18.7 via visualstudio-docs-pr#15433 (public mirror visualstudio-docs#11350) — no new PR needed
Phase 5.6 — release-checklist process-improvement PR dotnet/msbuild#14017

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 18.6
{{THIS_RELEASE_VERSION}} Version being released now 18.7
{{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.7.0 (bumped to 18.7.1 on the inserted build to enable OptProf-fresh insertion)
{{NEXT_VERSION}} Version that main will be bumped to 18.8
{{BRANCH_SNAP_DATE}} Date we create vs18.7 from main. ~2026-04-24 (estimated; branch existed by 2026-04-30 when merge-chain update PR #13643 merged)
{{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-01
{{STABLE_SNAP_DATE}} Date VS snaps rel/insiders → rel/stable. From VS-Dates wiki 2026-05-27
{{VS_SHIP_DATE}} Date VS ships publicly (GA). Post-GA tasks (nuget.org, docs) happen after this. 2026-06-09
{{PACKAGE_VALIDATION_BASELINE_VERSION}} Latest 18.7.0-preview-NNNNN-NN MSBuild build reachable from vs18.7. Used as the ApiCompat baseline for the bumped main. How to determine it: see the release skill. 18.7.0-preview-26229-01 (matches the 18.7 preview just inserted into VS main)

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

  • Release branch: vs18.7
  • DARC channel: VS 18.7 (ID 10189)
  • Next DARC channel: VS 18.8 (ID 10188)
  • 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 had VersionPrefix = 18.7.0 at the time of the snap
    • Confirm branch vs18.7 did not already exist
    • Confirm DARC channel VS 18.7 exists (ID: 10189):
      darc get-channels
  • Create this tracking issue in dotnet/msbuild with all {{PLACEHOLDERS}} replaced
  • As phases complete, record artifact URLs in the Release Output table at the top of this checklist.

Phase 1: Branch & Prepare

Trigger: ~2026-04-24 reached.

Steps are sequential — complete in order.

  • 1.0 Pre-snap team check. Before snapping the branch, ping the MSBuild team to confirm there is nothing they still need to merge into main that should ship in 18.7. Anything that lands in main after Phase 1.1 will go into 18.8 instead.
    (Not explicitly tracked in this release; step is new in the updated checklist.)
  • 1.1 Create branch vs18.7 from HEAD of main (requires repo admin rights — git push to refs/heads/vs* is restricted; if you don't have permission, ask a repo admin with vs* push rights to do it):
    git push upstream HEAD:refs/heads/vs18.7
    • 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.7
  • 1.2 DARC configuration — batch all channel/mapping changes into one PR on the maestro-configuration repo.
    Use --configuration-branch msbuild-18.7 on every command and --no-pr on all but the last:
    • 1.2a Ensure branch-to-channel association exists:
      darc add-default-channel --channel "VS 18.7" --branch vs18.7 --repo https://github.com/dotnet/msbuild --configuration-branch msbuild-18.7 --no-pr
    • 1.2b Create DARC channel for next release:
      darc add-channel --name "VS 18.8" --configuration-branch msbuild-18.7 --no-pr
      Channel VS 18.8 already existed (ID 10188), so this was 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.8" --branch vs18.8 --repo https://github.com/dotnet/msbuild --configuration-branch msbuild-18.7
    • 1.2d Get the maestro-configuration PR reviewed and merged: https://dev.azure.com/dnceng/internal/_git/maestro-configuration/pullrequest/60575
  • 1.3 Update .config/git-merge-flow-config.jsonc:
    • 1.3a Insert vs18.7 as the last entry before main in the merge chain. Add a comment noting the VS/SDK version context. Done via PR Update merge-flow config for vs18.7 release branch #13643 (merged 2026-04-30); follow-up auto-merge-flow PR [automated] Merge branch 'vs18.7' => 'main' #13659 still pending.
    • 1.3b Retire predecessor branches that will no longer be supported. Remove their MergeToBranch entries and rewire the chain to skip them so automation does not open stale forward-merge PRs.
      (Not explicitly tracked in this release; step is new in the updated checklist.)
      How to identify a retired branch:
      • The combined rule: a branch paired with both an SDK band and a VS version is retired only when both lifecycles agree it is out of support. If only one side says retired but the other is still supported, keep the branch — automation must still flow forward-merges so the still-supported lifecycle keeps receiving fixes.
      • SDK lifecycle — for branches paired with an SDK band, check https://learn.microsoft.com/dotnet/core/porting/versioning-sdk-msbuild-vs#lifecycle. If the paired SDK band is past its support end date, the branch is SDK-retired.
      • VS lifecycle — check the VS Servicing Information wiki. Rule of thumb: the VS support window covers the current release plus two preceding versions, so the first candidate for VS-retirement is vs18.7 - 3 = vs18.4 — always confirm on the wiki, since servicing exceptions can extend specific versions beyond the rule of thumb.
      • VS-only branches (not paired with any active SDK band) are retired purely on the VS lifecycle.

Phase 2: DARC Subscription Updates

Trigger: vs18.7 branch exists (Phase 1 complete).
Why this runs before bumping main: consumers of MSBuild via main (notably the VMR) should start receiving next-version bits from the VS 18.8 channel the moment main is bumped. Reassigning main's default channel before the Phase 3 branding bump means the first main build at the new version is already published to the correct channel; otherwise it lands on the now-stale VS 18.7 channel.

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

  • 2.1 Find the SDK main subscription ID to update:
    darc get-subscriptions --exact --source-repo https://github.com/dotnet/msbuild --channel "VS 18.7"
    Found: d1c6afb2-7bf1-43e4-8f2e-af7e0680b540
  • 2.2 Verify release branch channel association:
    darc get-default-channels --source-repo https://github.com/dotnet/msbuild --branch vs18.7
    vs18.7 → VS 18.7 association already existed (id 6921) — 2.3d not needed.

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

  • 2.3 DARC channel/subscription updates:
    • 2.3a Remove main → old channel mapping:
      darc delete-default-channel --repo https://github.com/dotnet/msbuild --branch main --channel "VS 18.7" --configuration-branch msbuild-18.7-main-bump --no-pr
      → maestro-config PR #60704
    • 2.3b Associate main with next channel:
      darc add-default-channel --channel "VS 18.8" --branch main --repo https://github.com/dotnet/msbuild --configuration-branch msbuild-18.7-main-bump --no-pr
      → maestro-config PR #60705
    • 2.3c Update SDK main subscription to new channel:
      darc update-subscription --id d1c6afb2-7bf1-43e4-8f2e-af7e0680b540 --channel "VS 18.8" --configuration-branch msbuild-18.7-main-bump --no-pr
      → maestro-config PR #60706
    • 2.3d N/A — vs18.7 → VS 18.7 association already existed (verified in 2.2).
    • 2.3e Delete subscriptions for retired branches. For each branch identified as retired in step 1.3b (apply the same combined SDK+VS rule — do not delete subscriptions for a branch that's retired on only one side, since fixes must keep flowing into the still-supported lifecycle), remove its inbound subscriptions and any default channel associations.
      (Not tracked in this release; step is new in the updated checklist.)
    • 2.3f N/A — Arcade subscription was correct, no fix-up needed.
    • 2.3g Create the PR — N/A for 18.7 because each write produced its own PR (see deviation note above).
    • 2.3h Get the maestro-configuration PR(s) reviewed and merged: all three of #60704, #60705, #60706 still open.

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

  • 2.4 Verify the Arcade subscription for vs18.7:
    darc get-subscriptions --exact --target-repo https://github.com/dotnet/msbuild --source-repo https://github.com/dotnet/arcade
    Result: Enabled: True, source channel .NET 10 Eng. ✓

Roslyn subscription verification intentionally omitted from the per-release checklist: there is always exactly one Roslyn subscription, targeting main only and its channel does not rotate with SDK bands.

NuGet subscription: when the next-to-ship SDK band rotates (e.g. 4xx → 5xx), the NuGet → msbuild/main subscription must be re-pointed to the new band's channel. For 18.7: no SDK band rotation, so no re-point was required. (The old template's per-release NuGet/Roslyn verifications + the "should be Enabled: False" assertion have been removed; both subscriptions remained Enabled: True — this is intentional under the new policy.)

Phase 3: Bump Main & Update Pipelines

Trigger: Phase 2 DARC updates merged (main's default channel is now VS 18.8).

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

  • 3.1 eng/Versions.props: Update VersionPrefix to 18.8.0
  • 3.2 eng/Versions.props: Update PackageValidationBaselineVersion to 18.7.0-preview-26229-01 (matches the 18.7 preview just inserted into VS main). See How to determine PACKAGE_VALIDATION_BASELINE_VERSION in the release skill.
  • 3.3 Not needed — ApiCompat passed; no CompatibilitySuppressions.xml updates were required this release.
  • 3.4 Merge main-bump PR: #13657 — OPEN, BLOCKED on pre-existing broken-on-main test Microsoft.Build.Utilities.UnitTests_net472_x86. Needs admin merge or test fix.

Phase 4: Final Branding & VS Insertion

Trigger: 7 calendar days before 2026-05-01 (i.e., ~2026-04-24).
Precondition: Phases 1–3 complete. Preview builds from vs18.7 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.7 branch:
    No-op for 18.7 — no non-empty PublicAPI.Unshipped.txt entries on vs18.7.
  • 4.2 Run scripts/Stabilize-Release.ps1 on vs18.7 branch (applied via PR Final branding for 18.7 release #13658).
  • 4.3 Create and merge final branding PR to vs18.7: #13658 — MERGED 2026-04-30 12:27 UTC (commit 6ed5e9aa).
  • 4.4 Bootstrap OptProf for vs18.7. After the final-branding commit (4.3) merged, the official build was auto-triggered without OptProf data for the new branch and failed. Workaround applied:
    • 4.4a Cancel the auto-triggered official build for vs18.7.
    • 4.4b Re-run the official build manually for vs18.7 with the OptProf override from main — set Optional OptProfDrop Override to main's latest OptProf drop path. For 18.7 the override path was …/main/20260428.11/13968297/1 per rainersigwald's guidance, producing build 13982412 (20260430.11, version 18.7.1).
  • 4.5 Get M2 or QB approval as necessary per the VS schedule.
    18.7 needed this approval (release was running close to the schedule).
  • 4.6 Babysit the VS insertion PR from vs18.7 into VS main: devdiv VS PR #734106 — merged 2026-05-01 01:58 UTC (vs18.7 18.7.1-servicing-26230-11 → VS main, before the 5/1 insiders snap).

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

🛑 4.7 and 4.8 are NOT part of the regular release flow — skip them entirely on a normal release.
They only apply when servicing a previously-shipped release (i.e. you actually have a hotfix commit on vs18.7 that needs to be inserted into VS's already-snapped rel/insiders or rel/stable branch). If you have no such commit to service, leave AutoInsertTargetBranch untouched and move on to Phase 5.

⚠️ When you do need to service: re-confirm which VS branch you actually want to insert into before flipping AutoInsertTargetBranch. The default is main, so forgetting to retarget after the snap silently lands your fix in the next VS instead of the one you're servicing.

Phase 5: Post-GA

Trigger: 2026-06-09 has passed and VS release (18.7.0 Feature Update) has shipped. ← Today.

Steps are mostly parallel unless noted.

  • 5.1 Push packages to nuget.org. (5.1a–c verified; 5.1d email sent 2026-06-10.)

    How publishing works: We don't push packages ourselves. We hand a link to the Shipping artifacts of the official build to the dnceng release team, and they push to nuget.org. Searching past mail for the subject "Publish MSBuild 18.7 to NuGet.org" for the template.

    18.7 context (corrected 2026-06-10): nuget.org now has 18.6.3 published (the earlier note that 18.5/18.6 were not pushed and latest was v18.4.0 is stale). Tags v18.5.4 and v18.6.3 exist on upstream. Precedent therefore supports publishing 18.7.1 to nuget.org — proceed with the dnceng request (5.1d).

    • 5.1a Determine the exact MSBuild version that actually shipped to customers.
      Shipped version = 18.7.1 (18.7.1-servicing-26230-11) — confirmed from VS rel/stable .corext/Configs/msbuild-components.json (Microsoft.Build → 18.7.1-servicing-26230-11+024f5b0379cf99b95bc8939cd92a57912528b55c).
    • 5.1b Build that produced it: pipeline 9434, branch vs18.7, build 20260430.11 (id 13982412, result succeeded), source commit 024f5b0379cf99b95bc8939cd92a57912528b55c. Build run.
    • 5.1c PackageArtifacts verified — all 7 shipping nupkgs present as 18.7.1:
      • Microsoft.Build.Utilities.Core.18.7.1.nupkg
      • Microsoft.Build.18.7.1.nupkg
      • Microsoft.Build.Framework.18.7.1.nupkg
      • Microsoft.Build.Runtime.18.7.1.nupkg
      • Microsoft.Build.Tasks.Core.18.7.1.nupkg
      • Microsoft.NET.StringTools.18.7.1.nupkg
      • Microsoft.Build.Templates.18.7.1.nupkg
    • 5.1d Email the dnceng release team with the artifacts-shipping link from build 13982412 and ask them to publish 18.7.1 to nuget.org. Sent 2026-06-10.

  • 5.2 Publish docs

    How publishing works: The reference-publishing vendor team generates Microsoft Learn reference pages from the shipped MSBuild assemblies/xmldoc and then sends us a docs-repo PR with the regenerated content.

    • 5.2a Created reference-publishing ticket msft-skilling/Content #586884 — cloned from the latest (18.6) ticket #578189 and updated to 18.7. Now waiting for the vendor team to open the generated docs PR.
    • 5.2b Review and approve the docs-repo PR the vendor team opens (example: msbuild-api-docs#61). (Pending — tracked by ticket #586884; will arrive after the vendor processes 5.2a.)
    • 5.2c Change-waves Learn page sync. documentation/wiki/ChangeWaves.md gained a ### 18.7 section, but the public Change Waves Learn page was already synced with 18.7 (and 18.8) by the vendor on 2026-05-22 via visualstudio-docs-pr#15433 (public mirror #11350). Verified the page's #### 18.7 entries match main. No new PR needed.

  • 5.3 Create GitHub release: DONE → v18.7.1

    • 5.3a Precondition — previous release tag exists on upstream. Verified: v18.6.3 is present on upstream (and v18.5.4). (The earlier note claiming latest tag was v18.4.0 and that v18.5.0/v18.6.0 were never pushed is stale — the convention is to tag the shipped servicing version, e.g. v18.5.4, v18.6.3.)
    • 5.3b Commit tagged. Source commit of build 20260430.11: 024f5b0379cf99b95bc8939cd92a57912528b55c ("Bump version prefix from 18.7.0 to 18.7.1 (Bump version prefix from 18.7.0 to 18.7.1 #13664)").
    • 5.3c Tagged and pushed (lightweight tag, matching prior convention): 
      git tag v18.7.1 024f5b0379cf99b95bc8939cd92a57912528b55c
git push upstream v18.7.1
    • 5.3d Release published at https://github.com/dotnet/msbuild/releases/tag/v18.7.1 (auto-generated notes, compared from v18.6.3; not a draft, not prerelease).

  • 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. 18.7 note: main has already advanced to VS 18.9 (BootstrapSdkVersion 10.0.300, targeting the 10.0.4xx band); the bootstrap-SDK refresh on main is decoupled from 18.7 post-GA and handled by the current release cadence. vs18.7 stays pinned at 10.0.108.

  • 5.4b Update tools.dotnet in global.json to the latest released SDK in the targeted band. (Same note as 5.4 — main's global.json is at 10.0.300.)

  • 5.5 Verify the overall subscription map across every still-supported branch — each vsXX.Y branch has an Arcade subscription matching its targeted .NET band, and each supported branch's outbound subscriptions land in the right downstream (e.g. SDK band, VMR). You can find more info here.
    Findings (2026-06-10) — map is correct:

    • ✅ Inbound Arcade: vs18.7 ← dotnet/arcade (.NET 10 Eng) exists, matching its band.
    • ✅ Default channel: vs18.7 → VS 18.7 mapping present.
    • ✅ Outbound VMR (expected): VS 18.7 and VS 18.8 intentionally have no outbound dotnet/dotnet subscription. MSBuild ships more often than the SDK, so only the latest VS minor and the band-representative one (≈1 in 3, aligned to an SDK feature band) are VMR-bound — currently VS 18.6 → release/10.0.3xx and VS 18.9 → release/10.0.4xx/main. VS 18.7/18.8 flow forward via the merge chain instead. No change needed.

  • 5.6 Review this tracking issue for any process deviations. If the process changed, create a PR to update documentation/release-checklist.md with the improvements. → PR dotnet/msbuild#14017 (read shipped version from VS rel/stable; correct the "always x.0" guidance for OptProf x.1 bumps; de-ping the template). \

If 18.8 is a new major version

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions