Extend azsdk_typespec_generate_authoring_plan with SDK breaking change detection#15077
Extend azsdk_typespec_generate_authoring_plan with SDK breaking change detection#15077
Conversation
Catalogs 10 known TypeSpec change patterns that cause SDK breaking changes: - Per-language impact matrix (Java/.NET/Python/Go) - Language-scoped client.tsp mitigations with concrete code examples - Detection sources (TypeSpec diff vs SDK changelog) - Complex enum split case with multi-step decorator guidance - Language-specific breaking change policies Used by azsdk_typespec_generate_authoring_plan via RAG to warn developers about SDK impact during TypeSpec authoring, before merge. Ref: #15069, #13972, #14675 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
the
azsdk-cli
|
The following pipelines have been queued for testing: |
…e detection - Load sdk-breaking-patterns.md from eng/common/knowledge/ and inject as additional context so the AI agent includes SDK IMPACT warnings when planned TypeSpec changes match known breaking patterns - Add optional sdkChangelog parameter for deeper detection from SDK changelog - Add IGitHelper dependency for repo root discovery (same pattern as TypeSpecCustomizationService) - Update tool description to mention SDK breaking change detection - Build succeeds with 0 errors Ref: #15069, #13972, #14675 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
samvaity
force-pushed
the
savaity/sdk-breaking-patterns
branch
from
6e4401c to
cb61d4e
Compare
The most common failure in enum split mitigation is forgetting to rename the original enum out of the way before creating a replacement with the same @@clientName. This was the exact gap found in Storage testing (Issue #14675) — tool got steps 2-4 right but missed step 1. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
The following pipelines have been queued for testing: |
|
The following pipelines have been queued for testing: |
…reaking change detection
|
The following pipelines have been queued for testing: |
… Java, Python, Go, JS Added 10 new patterns (total 20) sourced from official per-language breaking change guides: - Enum value name changes (numeric names, Pattern 3) - Client name changes (Pattern 13) - Resource base type changes, .NET-specific (Pattern 14) - WirePathAttribute missing, .NET MPG-specific (Pattern 15) - Common types upgrade - accept (Pattern 16) - Unreferenced models removed - accept (Pattern 17) - Multi-level unflattened properties, Python-specific (Pattern 18) - Property name conflicts with base methods, Python-specific (Pattern 19) - LRO/Paging operation type changes, Go-specific (Pattern 20) - Enhanced operation signature pattern with Python @@OverRide example (Pattern 10) Enhanced Language-Specific Breaking Change Policies section with per-language references, customization mechanisms, and known accept-patterns. Key additions: - Go: many breaking changes CANNOT be resolved via client.tsp - .NET: @@markAsPageable, @@hierarchyBuilding, WirePathAttribute via tspconfig - Python: @@OverRide for parameter reorder, accept patterns for common types - JS: three-way merge workflow, TypeSpec-first recommendation - Per-language changelog pattern examples for each pattern Sources: - .NET: azure-sdk-for-net/.github/skills/mitigate-breaking-changes/SKILL.md - Java: azure-sdk-for-java/docs/contributor/typespec-quickstart.md - Python: azure-sdk-for-python/doc/dev/mgmt/sdk-breaking-changes-guide.md - Go: azure-sdk-for-go/documentation/development/breaking-changes/sdk-breaking-changes-guide.md - JS: aka.ms/azsdk/js/customization Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
The following pipelines have been queued for testing: |
3 participants
Summary
Extends the TypeSpec authoring plan tool to detect SDK breaking changes during authoring, before merge.
Today: Write TypeSpec → merge → pipeline fails → weeks of back-and-forth
After: Write TypeSpec → authoring plan warns with SDK impact → dev fixes in same session
Changes
New:
eng/common/knowledge/sdk-breaking-patterns.mdclient.tspmitigations with concrete code examplesUpdated:
TypeSpecAuthoringTool.cssdk-breaking-patterns.mdfromeng/common/knowledge/and injects as additional contextsdkChangelogparameter for deeper detection from SDK changelogIGitHelperdependency for repo root discovery (same pattern asTypeSpecCustomizationService)How It Works
The authoring plan tool already sends requests to
IAzureSdkKnowledgeBaseService. The breaking change patterns document is loaded from the file system and injected asAdditionalInfocontext. The AI agent picks up relevant patterns via its existing reasoning and includes warnings in the plan output.No SDK repo needed — works entirely from TypeSpec diff + patterns. Zero overhead for non-breaking changes.
Related