Skip to content

Commit

Permalink
Update ci-fix.md: dedup breaking changes guidance (#28441)
Browse files Browse the repository at this point in the history
  • Loading branch information
Konrad Jamrozik authored and vxfield committed Mar 28, 2024
1 parent 6e7d329 commit 1589d7e
Showing 1 changed file with 3 additions and 12 deletions.
15 changes: 3 additions & 12 deletions documentation/ci-fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,20 +126,11 @@ Refer to [Semantic and Model Violations Reference](https://github.com/Azure/azur

## `Swagger BreakingChange` and `BreakingChange(Cross-Version)`

- An API contract is identified by its api-version value. Once published, no changes to this API contract are allowed. This applies regardless of whether the API contract is for private preview, public preview, or GA (stable).
- The same-version breaking change linter rules check for changes to an existing api-version OpenAPI spec.
- When introducing a new API contract (preview or not), the new API contract must be backwards compatible with the previous GA’s API contract.
- However, during a (private or public) preview cycle, a new preview API contract does not have to be backwards compatible with the previous preview API contract although it must still be backwards compatible with the latest GA API contract.
- The cross version breaking change linter rules checks for this by comparing the new OpenAPI spec with the latest GA OpenAPI spec. If there is no latest GA OpenAPI spec, then the latest preview if it > 1 year old. If nether a GA or preview > 1 year old exists, then the OpenAPI spec is considered good.

### Adding label on PR automatically

The breaking change check has two types of violations: one is breaking change in the same version but not breaking change in a new version, the other is breaking change even in a new version.
For the former, a label 'NewApiVersionRequired' will be added automatically; For the latter, a label 'BreakingChangeReviewRequired' will be added automatically. Adding each label will trigger a github comment with guldance on how to fix.
See [aka.ms/azsdk/pr-brch-deep](https://aka.ms/azsdk/pr-brch-deep). If you want a quick read, see only [the `summary` section](https://aka.ms/azsdk/pr-brch-deep#summary).

### Run `oad` locally

To repro issues with "breaking changes" checks, you can locally run the tool that powers them [Azure/openapi-diff](https://github.com/Azure/openapi-diff) aka `oad`:
To repro issues with "breaking changes" checks, you can locally run the tool that powers them: [Azure/openapi-diff](https://github.com/Azure/openapi-diff), aka `oad`:
```
npm install -g @azure/oad
oad compare <old-spec-path> <new-spec-path>
Expand Down Expand Up @@ -306,4 +297,4 @@ Following checks have been removed from the validation toolchain as of August 20
[aka.ms/azsdk/support/specreview-channel]: https://aka.ms/azsdk/support/specreview-channel
[aka.ms/azsdk/support]: https://aka.ms/azsdk/support
[TypeSpec Discussions Teams channel]: https://teams.microsoft.com/l/channel/19%3A906c1efbbec54dc8949ac736633e6bdf%40thread.skype/TypeSpec%20Discussion%20%F0%9F%90%AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
[APIView Support Teams Channel]: https://teams.microsoft.com/l/channel/19%3A3adeba4aa1164f1c889e148b1b3e3ddd%40thread.skype/APIView?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
[APIView Support Teams Channel]: https://teams.microsoft.com/l/channel/19%3A3adeba4aa1164f1c889e148b1b3e3ddd%40thread.skype/APIView?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

0 comments on commit 1589d7e

Please sign in to comment.