Azure CLI Breaking Change Pre-Announcement

Microsoft

Apr 15, 2025

Background

In our continuous effort to improve the quality and timeliness of our documentation, we have embarked on an initiative to automate the production of Upcoming Breaking Change Documentation. This initiative aims to alleviate the workload and pressure typically experienced before major events such as Microsoft Build and Microsoft Ignite. By leveraging automated methods, we can ensure that our documentation is both comprehensive and promptly available to our users.

Streamlining the Process

To further streamline this process, we are introducing a new workflow designed to encourage Service Teams to notify us of any future breaking changes several sprints ahead. The new workflow includes a new framework to pre-announce breaking changes, which will enable us to publish detailed and accurate Upcoming Breaking Change Documentation well ahead of time, providing our users with the information they need to prepare for these changes.

Breaking Change Rule

Core CLI

A breaking change in Azure CLI refers to a modification that disrupts backward compatibility with previous versions, potentially causing scripts or automation written in earlier versions to fail. Common examples include modifying parameter names, input logic, result output format, behavior models, and adding additional verifications.

To mitigate the impact, Azure CLI coordinates half-yearly Breaking Change Releases, bundling multiple breaking changes together. This approach helps users plan ahead and adapt effectively.

Breaking Change Window

The breaking change window is a designated sprint for merging service command breaking changes, aligning with Microsoft Build in May and Microsoft Ignite in November. Outside this window, breaking changes are typically prohibited to ensure consistency and stability. Exceptions require high-grade justifications and are assessed based on overall impact.

30-Day Pre-announcement Policy

All breaking changes must be pre-announced 30 days (usually 2 sprints) before the release. This provides users with buffer time to adapt. Notifications are made through:

Warning Log: Mandatory pre-announcement while executing.
Upcoming Breaking Change Document: Automatic collection and listing of changes.

Extensions

All breaking changes in GA (General Available) extensions must be pre-announced at least 30 days prior to their release. While extensions do not need to follow the breaking change window, it is strongly recommended to align their releases with the Core Azure CLI breaking change window.

GA (General Available) Release with Breaking Change Pre-Announcement

Must include complete breaking change information.
Must fulfill the 30-day announcement requirement.

During the 30-day announcement period, releases are allowed for unrelated GA (General Available) versions and multiple preview releases (Beta versions).

By adhering to these guidelines, users can ensure a smoother transition and maintain compatibility with their existing scripts and automation.

How to Announce a Breaking Change

It is simple to announce a Breaking Change using the new framework.

Find the entry:

Find or add an entry to the _breaking_change.py file in the top-level directory of the relevant module.

Register Breaking Changes:

You can then pre-announce breaking changes for different command groups or commands. Multiple breaking changes on the same command are accepted.

from azure.cli.core.breaking_change import register_required_flag_breaking_change, register_default_value_breaking_change, register_other_breaking_change

register_required_flag_breaking_change('bar foo', '--name')
register_default_value_breaking_change('bar foo baz', '--foobar', 'A', 'B', target_version='May 2025')
register_other_breaking_change('bar foo baz', 'During May 2024, another Breaking Change would happen in Build Event.')

Try the Warning

All related breaking changes will be displayed when executing the command. For instance, with the above declarations, the following warnings will be output when executing the command:

# The azure command
az bar foo baz

# =====Warning output=====
# The argument '--name' will become required in next breaking change release (2.61.0).
# The default value of '--foobar' will be changed to 'B' from 'A' in May 2025.
# During May 2024, another Breaking Change would happen in Build Event.

Types of Breaking Changes

There are several types of breaking changes defined in `_breaking_change.py`. You should use any of them to declare breaking changes:

Remove
Rename
Output Change
Change
Default Change
Be Required
Other Changes
Conditional Breaking Change

Work with Breaking Change Detect

To normalize the release of breaking changes, Azure CLI has integrated a Breaking Change Detection tool into the Pull Request Pipeline. This tool will reject any breaking changes that are submitted outside of the designated breaking change window and will provide guidelines for following the breaking change policies.

Technical Implementation

The Breaking Change Pre-Announcement uses a hook in the Azure CLI. This hook is used to collect announcements registered in _breaking_change.py files and transform them into tags that can be consumed by the Knack framework, which is the foundational framework used by the Azure CLI. When multiple tags are registered under the same identifier, they are consolidated into a single MergedTag. This MergedTag is then used to manage complex scenarios effectively.

Conditional breaking changes are not transformed into tags. Instead, they are stored in the breaking changes registry. These changes can be accessed manually by calling the print_conditional_breaking_change function.