assessing-breaking-changes
Backward Compatibility in MSBuild
Backward compatibility is the default — any change that could alter existing build behavior must be explicitly justified.
This skill covers how to evaluate compatibility risk. For the mechanics of ChangeWave implementation, see the changewaves skill.
Core Philosophy
- Existing builds must not break. If a project built successfully yesterday, it must build successfully today with identical semantics.
- New warnings are breaking changes. Builds that use
-WarnAsErroror<TreatWarningsAsErrors>true</TreatWarningsAsErrors>will fail if you introduce a new warning. Always gate new warnings behind a ChangeWave or emit them asMessageimportance instead. - Output changes are behavioral changes. Even "improvements" to output formatting, file paths, or diagnostic text can break downstream consumers that parse MSBuild output.
- Removal is nearly impossible. Never remove CLI switches, public APIs, or property names. Deprecate with warnings first, then gate removal behind a ChangeWave after multiple release cycles.
Blast Radius Checklist
Before merging any behavioral change, evaluate:
More from dotnet/msbuild
multithreaded-task-migration
Guide for migrating MSBuild tasks to multithreaded mode support, including compatibility red-team review. Use this when converting tasks to thread-safe versions, implementing IMultiThreadableTask, adding TaskEnvironment support, or auditing migrations for behavioral compatibility.
36changewaves
Manage MSBuild Change Waves: create new waves, condition features behind opt-out flags, write tests for wave-gated features, document change waves in ChangeWaves.md, and retire expired waves. Use when adding changes that need an opt-out or rotating out old change waves. Changes that introduce a user-visible behavior change should consider whether to use a changewave.
2merge-dependency-updates
Review and merge open bot PRs: dependency updates from dotnet-maestro, codeflow from dotnet/dotnet, and OneLoc localization PRs. Produces a clickable dashboard with CI status, review state, and suspicious file flags. Use when you want to triage all open bot PRs in one pass.
2use-bootstrap-msbuild
Guide for testing bug reproductions against locally-built MSBuild. Use this when you have a repro project and want to verify a fix works before submitting a PR.
2deploy-msbuild-to-vs
Deploy locally-built MSBuild binaries into a Visual Studio installation for testing and debugging. Use when you need VS itself to use your local MSBuild changes, or when debugging MSBuild as invoked by VS.
2pipelines-health-check
Check health of MSBuild CI pipelines, VS repo PR insertion statuses, and VMR codeflow PRs. Use when asked about pipeline health, build failures, infrastructure issues, CI status, insertion PR status, VMR codeflow status, or for periodic health monitoring.
2