Integrate .NET into the SDK breaking change detection and mitigation flow
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 130
Description
## Context
The SDK Breaking Change Detection and Mitigation Framework currently supports Go, Java, Python, and JavaScript through `azsdk_package_detect_breaking_change` and the `azsdk-common-sdk-breaking-change` skill. .NET should join the same framework so that service teams get a consistent cross-language experience in:
- Inner-loop development
- Spec PR validation
- SDK PR validation
.NET already uses `Microsoft.DotNet.ApiCompat` to enforce API compatibility during builds and already has deterministic mitigation capabilities in the generator and the `mitigate-breaking-changes` skill. We should reuse those investments rather than introduce a competing compatibility implementation, and address any gaps needed by the common framework.
## Goal
Integrate .NET (C#) into the end-to-end SDK breaking change detection and mitigation flow, using ApiCompat as the primary compatibility implementation while preserving the framework's common inputs, structured outputs, classification, and mitigation experience.
The integration should identify SDK-level changes early, distinguish deterministic mitigations from cases requiring LLM or user judgment, and avoid requiring partners to understand language-specific implementation details.
## Workstreams
### 1. Detect .NET SDK changes with ApiCompat
- Compare a generated .NET package with the latest GA package using ApiCompat.
- Run compatibility detection independently from source compilation and analyzer validation so unrelated build failures do not obscure compatibility results.
- Adapt ApiCompat results to the common `azsdk_package_detect_breaking_change` contract, including structured change details and `hasBreakingChange`.
- Identify and address gaps where ApiCompat reports only compatibility violations rather than the underlying API change. The framework needs enough information to represent additions, removals, signature changes, and paired transformations such as renames so downstream analysis can classify the change and recommend the correct mitigation.
- Preserve useful ApiCompat diagnostics and make unsupported or ambiguous cases explicit rather than guessing.
This work should build on #15558.
### 2. Define .NET breaking-change patterns
- Define the .NET SDK-change-to-breaking-change pattern catalog used to classify changes, explain their root cause, and select mitigation strategies.
- Include both changes that can be handled deterministically during generation and changes that require TypeSpec customization, LLM reasoning, or user judgment.
- Cover management-plane and data-plane libraries, with management-plane support first if sequencing is needed.
This work should build on #15564.
### 3. Integrate mitigation
- Connect detected and classified .NET changes to the existing .NET `mitigate-breaking-changes` skill.
- Reuse existing generator mitigations for deterministic scenarios.
- Integrate `azsdk_typespec_customized_code_update` where a client customization is the appropriate resolution.
- Clearly surface changes that cannot be safely mitigated automatically for LLM-assisted or manual resolution.
### 4. Wire the common workflows
- Enable .NET in the common inner-loop, spec PR, and SDK PR breaking-change workflows.
- Add the required .NET SDK repository configuration for the detector, pattern catalog, and mitigation entry points.
- Keep the user-facing workflow and result shape consistent with the other supported SDK languages.
## Acceptance criteria
- [ ] `azsdk_package_detect_breaking_change` accepts a .NET SDK package and compares it with the latest GA package.
- [ ] ApiCompat is the primary .NET compatibility implementation; any required supplemental change extraction is documented and scoped to identified gaps.
- [ ] Compatibility detection can run independently of compilation and analyzer validation.
- [ ] The detector emits the framework's structured result, including actionable API change details and `hasBreakingChange`.
- [ ] .NET breaking-change patterns classify supported changes, explain root causes, and identify appropriate mitigation paths.
- [ ] The common mitigation flow invokes existing .NET mitigation capabilities, including generator-based mitigation and `azsdk_typespec_customized_code_update` where applicable.
- [ ] Ambiguous or non-deterministic changes are surfaced for LLM or user judgment rather than automatically applying an unsafe fix.
- [ ] .NET is wired into inner-loop, spec PR, and SDK PR scenarios with a partner experience consistent with the other languages.
- [ ] Automated tests cover result adaptation, representative compatibility patterns, separation from build/analyzer failures, and mitigation routing.
## Related
- #15553
- #15558
- #15559
- #15564
- SDK breaking change detector spec: https://github.com/Azure/azure-sdk-tools/blob/main/tools/azsdk-cli/docs/specs/sdk-breaking-change-detect.spec.md
- Breaking change detection and mitigation skill: https://github.com/Azure/azure-sdk-tools/pull/16634
Contributor guide
Assessment
This issue has not been assessed yet.