* Added doc for sdk suppression

* Resolved review comment
This commit is contained in:
Ray Chen 2024-03-20 17:02:23 +08:00 коммит произвёл GitHub
Родитель 77b17b30a1
Коммит 44a81f85be
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
1 изменённых файлов: 39 добавлений и 0 удалений

Просмотреть файл

@ -0,0 +1,39 @@
# SDK Breaking Change Review Workflow
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](https://azure.github.io/azure-sdk/general_introduction.html#dependable), breaking changes are more harmful to a users 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 generation CI check result for a specific SDK, such as "azure-sdk-for-go", and 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
```
### 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.
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.