Managing MSBuild Change Waves

A Change Wave is an opt-out flag that groups risky features together. Users disable features by setting the environment variable MSBUILDDISABLEFEATURESFROMVERSION to the wave version. This skill covers the how — the full lifecycle: creating a wave, conditioning code on it, testing, documenting, and retiring.

For the when — deciding whether a change is a breaking change and whether it needs a ChangeWave at all — see assessing-breaking-changes.

Decide Whether a Change Wave Is Appropriate

Use a change wave when a change is valuable but has meaningful compatibility risk for existing builds.

Good candidates:

• User-visible behavior changes that may regress some build graphs.
• Changes in parsing/evaluation/execution semantics where real-world usage is broad or hard to predict.
• Changes that may require customer adaptation time and benefit from a temporary opt-out.