skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

assessing-breaking-changes

Assess backward compatibility risk of MSBuild behavioral changes and ChangeWave requirements.

1.2k|337|Updated Oct 13, 2022
Search Tags:#deprecation#backward compatibility#msbuild#DotNet#Breaking Changes#changewave#build warnings
One-click install
npx skills add https://github.com/dotnet/dotnet --skill assessing-breaking-changes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: assessing-breaking-changes
Source: https://github.com/dotnet/dotnet/tree/main/src/msbuild/.github/skills/assessing-breaking-changes
Command: npx skills add https://github.com/dotnet/dotnet --skill assessing-breaking-changes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

MSBuild changes that alter build behavior, add warnings, or change defaults can silently break existing builds, especially for users with TreatWarningsAsErrors enabled. This Skill provides a structured framework to evaluate compatibility risk before merging any behavioral change.

Core Features & Use Cases

  • Blast Radius Checklist: Systematically evaluate whether a change affects build outputs, warnings, property defaults, target ordering, or output formats.
  • ChangeWave Decision Framework: Determine when a change must be gated behind a ChangeWave versus when it can ship directly.
  • Warnings-as-Errors Guidance: Handle the common pitfall where new MSBxxxx warnings break enterprise builds using TreatWarningsAsErrors.
  • Use Case: You are adding a new diagnostic warning to MSBuild. Use this Skill to determine that the warning must be gated behind a ChangeWave because users with TreatWarningsAsErrors would see build failures.

Quick Start

Assess whether my MSBuild change that adds a new warning for deprecated task parameters requires a ChangeWave.

Frequently Asked Questions about assessing-breaking-changes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I know if my MSBuild change needs a ChangeWave?▼

A ChangeWave is required if the change alters what gets built, adds a new warning, changes a property default, or modifies target execution order. Internal refactorings, opt-in features, and low-blast-radius bug fixes typically do not need one.

Why is adding a new MSBuild warning considered a breaking change?▼

Many enterprise builds set TreatWarningsAsErrors to true, so any new MSBxxxx warning causes their builds to fail. Gate new warnings behind a ChangeWave or emit them as low-importance messages instead.

What should I test for MSBuild backward compatibility?▼

Verify multi-targeting projects, mixed-language solution builds, incremental builds, design-time builds in Visual Studio, cross-platform path handling, and builds with TreatWarningsAsErrors enabled.

When can MSBuild remove a deprecated feature or CLI switch?▼

Removal requires a deprecation warning first, documentation in release notes, and maintaining old behavior for at least two major .NET versions. Actual removal only happens after the ChangeWave has rotated out.

Does a bug fix in MSBuild require a ChangeWave?▼

Bug fixes that restore clearly intended behavior with limited blast radius usually ship without a ChangeWave. Use judgment on impact and add a regression test to validate the fix.

Related Skills

Explore More Software Engineering Skills→
radius-projectradius-project
1.7k

radius-update-doc

Patches existing contributor docs that drifted from changed code with minimal targeted edits.

Official
Intermediate
dotnetdotnet
1.2k

changewaves

Coordinate MSBuild feature changes behind opt-out Change Waves.

Official
Advanced
mtsatryanmtsatryan
1

build-engineer

Optimize software build systems to reduce compile times and improve reproducibility.

Community
Advanced
ZaxbyHubZaxbyHub
437

opt-in-tool-registration

Enforce consistent opt-in tool registration and feature flag gating patterns.

Official
Intermediate