SDK Breaking Changes

Short Link:	aka.ms/azsdk/sdk-suppression

Table of Contents

• Overview
• How to Suppress the SDK Breaking Changes
• How Does the Suppression Work
• How to Get the Suppression Reviewed

Overview

When a specification pull request has breaking change for a specific SDK language, such as Go, the pull request will be labelled with "BreakingChange-Go-Sdk". According to the design principles of Azure SDK, breaking changes are more harmful to a user’s experience than most new features and improvements are beneficial. Therefore, the pull request author will be strongly encouraged to update the API specification to remove the breaking changes for the SDK. If the breaking change cannot be mitigated by a specification change, the author will need to suppress the breaking changes and have the suppression reviewed. See the following section for details on how to suppress breaking changes.

Once the suppression is added to the pull request, SDK reviewers will evaluate the suppressions and either provide feedback or approve the suppressions. When the suppressions have been approved, the SDK breaking change review is complete and the pull request can proceed to the next stage.

Note: both the suppressions review and the SDK breaking change review will be conducted proactively by SDK reviewers, and the expected completion time is around 48 business hours.

How to Suppress the SDK Breaking Changes

To suppress SDK breaking changes, go to the SDK Validation * CI check result for a specific SDK language, such as "SDK Validation - Go". Click on the link of View more details on Azure Pipelines to browse to the azure pipeline result page. Then download the artifact of spec-gen-sdk logs. There is a html report with the name ended by "-gen-result.html". Open the html report then look for the Absent SDK breaking changes suppressions section, as shown in the following code block:

Absent SDK breaking changes suppressions
- Function `*LinkerClient.BeginCreateOrUpdate` has been removed
- Function `*LinkerClient.NewListPager` has been removed

Note: refer to https://aka.ms/azsdk/sdk-automation-faq to download the html report.

Next Steps

1. The pull request authors create a file called sdk-suppressions.yaml if it doesn't already exist in your service folder in the azure-rest-api-specs repository.

   • For TypeSpec scenarios, sdk-suppressions.yaml should be placed in the root folder of the TypeSpec project, which also contains the tspconfig.yaml file. For example, refers to the location for Contoso.Management.
   • For OpenAPI scenarios, sdk-suppressions.yaml should be placed in the {service}\resource-manager folder. For example, see the location for the contosowidgetmanager resource provider.

2. The pull request authors copy every line under the Absent SDK breaking changes suppressions section to the suppression file in the following format:

suppressions:
  azure-sdk-for-go:
    - package: 'sdk/resourcemanager/servicelinker/armservicelinker'
      breaking-changes:
        - Function `*LinkerClient.BeginCreateOrUpdate` has been removed
        - Function `*LinkerClient.NewListPager` has been removed

3. The pull request authors add this suppression file change to your spec pull request. Then the suppressions will be recognized by the bot, and the corresponding suppression label will be added to the spec pull request. For example, for the azure-sdk-for-go, the label BreakingChange-Go-Sdk-Suppression will be added to the pull request.

4. The SDK reviewers will evaluate the suppressions and either approve them or provide feedback. If the suppressions are approved, the corresponding approval label will be added to the pull request. For example, for the azure-sdk-for-go, the label BreakingChange-Go-Sdk-Suppression-Approved will be added to the pull request.

How Does the Suppression Work

The suppression file will remain with the specification move with it to other branches or repositories(such as from the private specification repository to the public specification repository). The suppressions can be deleted after the SDK has been released to the public.

How to Get the Suppression Reviewed

SDK reviewers will monitor the specification pull requests with breaking change suppression lables. For example, for the azure-sdk-for-go, the label is BreakingChange-Go-Sdk-Suppression. They will evaluate the suppressions and either approve them or provide feedback. If the suppressions are approved, the corresponding approval label will be added to the pull request. For example, for the azure-sdk-for-go, the label BreakingChange-Go-Sdk-Suppression-Approved will be added to the pull request. Once the suppression review is complete, the pull request can proceed to the next stage.