Extend azsdk_typespec_generate_authoring_plan with SDK breaking change detection
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 143
Description
## Goal
When a dev writes TypeSpec, detect SDK breaking changes and include `client.tsp` mitigations in the authoring plan — before merge.
**Today:** Write TypeSpec → merge → pipeline fails → weeks of back-and-forth → fix client.tsp → repeat
**Target:** Write TypeSpec → authoring plan warns with SDK impact → dev fixes in same session → merge clean
## Background
- `azsdk_customized_code_update` against Storage breaking changes got 90% right (Issue #14675), confirming the patterns are well understood
- `azsdk_typespec_generate_authoring_plan` already knows all custom decorators and their applicable scenarios, but has limitations with complex cases (e.g., enum split into several enums)
- [Crystal's ](@chunyu3) testing showed that feeding SDK changelog into the tool enables accurate detection
## Work Plan
### Task 1: Build breaking change pattern database
**Where:** `eng/common/knowledge/sdk-breaking-patterns.md` (shared, reusable)
Document known breaking change patterns with:
- Detection rules (TypeSpec diff patterns and/or SDK changelog patterns)
- Per-language impact — the same TypeSpec change affects Java/.NET/Python/Go differently based on each language's breaking change policy and handling mechanisms
- Language-scoped mitigations using decorators with appropriate language scope
- Complexity level : simple patterns first (model rename) vs complex patterns (enum split into multiple enums with subset members)
**Known gap/ limitations :** Complex enum split scenario — tools know the right decorators but don't generate accurate sample code when an enum is split into several enums. Need concrete examples.
### Task 2: Extend `azsdk_typespec_generate_authoring_plan` with SDK impact warnings
**Where:** `azure-sdk-tools/tools/azsdk-cli/`
- After generating the authoring plan, match planned changes against pattern database
- Include SDK IMPACT warnings in plan output with language-specific impact and scoped `client.tsp` fix code
- Accept SDK changelog as additional input for deeper detection
- For non-breaking changes, return plan as-is (zero overhead)
### Task 3: Update `azure-typespec-author` skill to surface warnings
**Where:** `azure-rest-api-specs/.github/skills/azure-typespec-author/`
- Update SKILL.md workflow to include review of SDK impact warnings after Step 3 (plan retrieval)
- If warnings present, prompt user to accept and apply mitigations, or revise approach
### Task 4: Validate with Storage scenario end-to-end
Use [Crystal's](@chunyu3) Storage simulation (reverted PR #41684) as the test case:
- Feed Storage Java SDK changelog into `azsdk_typespec_generate_authoring_plan`
- Verify detection of all breaking change categories
- Verify correct language-scoped `client.tsp` mitigations, especially the enum split case
- Target: 90%+ accuracy
## Related
- Issue #14675 — Detect and Resolve mgmt. SDK Breaking Changes Early
- PR #14821 — Added customization workflow to generate-sdk-locally skill
- PR #41684 — Storage client.tsp fix (human reference for enum split case)
- PR #42089 — Crystal's agent session that triggered the skill successfully
Contributor guide
Assessment
This issue has not been assessed yet.