[v2] Publish the breaking-change inventory and migration guide

[SteveSandersonMS]

Summary

Publish the authoritative breaking-change inventory and migration guidance for Copilot SDK v2.

This work depends on the final decisions and implementations in the other v2 sub-issues.

Required content

• Per-language inventory of removed, renamed, and relocated APIs.
• Before-and-after examples for every accepted breaking change.
• Behavioral changes that may compile successfully but alter runtime behavior.
• Supported replacements for removed APIs.
• Runtime and CLI compatibility requirements.
• Package/version upgrade instructions.
• Links to the decision issues and implementation pull requests.
• Explicit notes for historical proposals that were retained, superseded, deferred, or moved elsewhere.

Completion

The migration guide is reviewed by each affected SDK owner, matches the shipped preview packages, and is linked from the v2 release notes and primary documentation.

[github-actions]

Documentation Gap Confirmed

Gap: There is currently no authoritative, consolidated migration guide covering the Copilot SDK v2 breaking changes. Individual sub-issues track specific decisions, but no single document aggregates them into user-facing guidance.

Affected docs: This is a net-new documentation deliverable rather than a fix to existing content. Likely locations:

• Top-level docs/ (new "Migration Guide" / "Breaking Changes" page, following .github/instructions/docs-style.instructions.md)
• Per-language README.md files (Node/TS, Python, Go, .NET, Rust, Java) may need "See migration guide" pointers
• v2 release notes / changelog entries, which should link to the guide

Suggested content to add:

1. A per-language table of removed/renamed/relocated APIs (old symbol → new symbol/location).
2. Before/after code snippets for each accepted breaking change.
3. A callout section for behavioral-only changes (code compiles but runtime behavior differs).
4. Recommended replacement APIs/patterns for anything removed.
5. Minimum CLI/runtime version requirements for v2.
6. Step-by-step package/version upgrade instructions per language/package manager.
7. Cross-links to each decision issue and its implementing PR.
8. A "Deferred / Retained / Superseded" appendix noting historical proposals not adopted, with rationale links.

Note: This issue is blocked pending final decisions from the linked v2 sub-issues (parent: #2522). The guide can be drafted incrementally as each sub-decision lands, then finalized once all are resolved.

Generated by Documentation Handler for #2527 · copilot · auto · 16.4 AIC · ⌖ 4.53 AIC · ⊞ 7K · ◷