Add experimental API annotations from schema stability markers#875
Add experimental API annotations from schema stability markers#875stephentoub wants to merge 7 commits intomainfrom
Conversation
Read the 'stability' field from api.schema.json and propagate it to generated code in all four SDK languages. APIs marked as experimental in the schema (fleet, agent, compaction) now carry appropriate annotations in the generated output. Changes to codegen scripts (scripts/codegen/): - utils.ts: Add stability field to RpcMethod; add isNodeFullyExperimental helper - csharp.ts: Emit [Experimental(Diagnostics.Experimental)] on types and API classes - typescript.ts: Emit /** @experimental */ JSDoc on types and groups - python.ts: Emit # Experimental comments on types and API classes, docstrings on methods - go.ts: Emit // Experimental: comments on types and API structs Design decisions: - When all methods in a group are experimental, the group/class is annotated and individual methods are not (annotation is inherited) - Data types (request/result) for experimental methods are also annotated - C# uses a Diagnostics.Experimental const ("GHCP001") referenced by all attributes - SDK csproj suppresses GHCP001 internally; consumers still see warnings Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Propagates "stability": "experimental" markers from @github/copilot’s api.schema.json through the repo’s code generators so the generated RPC surfaces across Node/TS, Python, Go, and .NET are annotated as experimental.
Changes:
- Extend the shared RPC schema model to carry
stabilityand addisNodeFullyExperimental()to detect fully-experimental groups. - Update all four language generators to emit experimental annotations at the group/type/method level.
- Regenerate SDK RPC outputs and add .NET project-level suppression for the emitted experimental diagnostic ID (
GHCP001) within the SDK/tests.
Reviewed changes
Copilot reviewed 8 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| scripts/codegen/utils.ts | Adds stability?: string to RpcMethod and introduces isNodeFullyExperimental() helper. |
| scripts/codegen/typescript.ts | Emits /** @experimental */ on generated TS types and on group/method wrappers where appropriate. |
| scripts/codegen/python.ts | Injects “Experimental” comments onto generated dataclasses and adds group/method warnings in wrappers. |
| scripts/codegen/go.ts | Injects “Experimental” comments for generated Go types and groups/methods in wrappers. |
| scripts/codegen/csharp.ts | Emits [Experimental(Diagnostics.Experimental)] attributes for experimental RPC groups/types/methods and generates Diagnostics.Experimental = "GHCP001". |
| nodejs/src/generated/rpc.ts | Regenerated TS RPC surface with @experimental JSDoc markers. |
| python/copilot/generated/rpc.py | Regenerated Python RPC surface with experimental comments and group markers. |
| go/rpc/generated_rpc.go | Regenerated Go RPC surface with experimental comments (currently not gofmt-clean). |
| dotnet/src/Generated/Rpc.cs | Regenerated C# RPC surface with Experimental attributes and Diagnostics constant. |
| dotnet/src/GitHub.Copilot.SDK.csproj | Suppresses GHCP001 during SDK build so the SDK can reference its own experimental APIs. |
| dotnet/test/GitHub.Copilot.SDK.Test.csproj | Suppresses GHCP001 during test builds so tests can reference experimental APIs. |
You can also share your feedback on Copilot code review. Take the survey.
Address review feedback: quicktype generates comments with trailing whitespace which fails gofmt checks. Add a post-processing step to strip trailing whitespace from the quicktype output before writing. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
gofmt requires tab indentation (not spaces) and column-aligns struct field declarations and composite literal keys. Updated the Go codegen to emit tabs for all indentation and compute proper padding for field alignment in wrapper structs and constructors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Cross-SDK Consistency ReviewI've reviewed this PR for consistency across all four SDK implementations (C#, TypeScript, Python, and Go), and I'm pleased to report that the changes maintain excellent cross-language consistency. What Was CheckedExperimental API annotations were added for these API groups:
Consistency Verification ✅All four SDKs implement the experimental annotations consistently:
Key Strengths
No Issues FoundNo cross-SDK inconsistencies detected. This PR successfully maintains feature parity across all SDK implementations. Note: This is an automated consistency review focusing on cross-language API parity.
|
gofmt expands single-line 'if err != nil { return nil, err }' into
multi-line blocks. Updated Go codegen to emit the multi-line form
directly, avoiding the gofmt diff.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Cross-SDK Consistency ReviewI've reviewed this PR for consistency across all four SDK implementations (TypeScript, Python, Go, and .NET). The implementation is excellent and maintains strong cross-language consistency. Here's what I verified: 🎯 Consistent Annotation StrategyAll four SDKs correctly implement experimental API annotations with appropriate language-specific conventions:
🔍 Verified Consistency Points
💡 Design QualityThe implementation shows excellent engineering:
🎉 SummaryNo consistency issues found. This PR successfully propagates experimental API markers from the schema to all four SDK implementations with consistent semantics and appropriate language-specific syntax. Great work! 🚀
|
gofmt expands single-line struct definitions with semicolons into multi-line format. Updated the Go codegen to emit API struct definitions in multi-line format directly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Cross-SDK Consistency Review: PASSEDI've reviewed this PR for cross-language consistency, and I'm pleased to report that all four SDK implementations maintain excellent feature parity for experimental API annotations. Consistency SummaryAll languages properly implement the three-level annotation strategy:
What I Verified✅ Codegen scripts - All four language generators ( ✅ Generated code - All experimental RPC methods ( ✅ API groups - FleetApi, AgentApi, and CompactionApi classes/groups are consistently marked experimental across all languages ✅ Data types - Request and result types for experimental methods are consistently annotated ✅ Language idioms - Each implementation uses the appropriate mechanism for its ecosystem:
C# Diagnostic HandlingThe C# implementation includes a particularly nice touch with the internal No consistency issues found. This is an exemplary cross-SDK feature implementation! 🎉
|
quicktype emits wide-spaced struct fields for column alignment, but gofmt doesn't column-align when fields have interleaved comments. Added post-processing to collapse excessive spacing in quicktype struct field lines and remove trailing blank lines from quicktype output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Cross-SDK Consistency Review: PASSEDI've reviewed this PR for consistency across all four SDK implementations (TypeScript, Python, Go, and .NET), and I'm pleased to report that the experimental API annotations are consistently implemented across all languages. ✅ What's Consistent1. API Group Annotations - All three fully-experimental groups are properly annotated:
2. Data Type Annotations - All request/result types for experimental methods are annotated:
3. Language-Idiomatic Annotations - Each SDK uses appropriate conventions:
4. Code Generation - All 4 codegen scripts ( 💡 Notes
Great work maintaining feature parity across all SDKs! 🎉
|
Removed manual quicktype column-alignment workaround and regenerated with Go installed locally so formatGoFile() runs gofmt properly. This ensures the committed output exactly matches what CI produces. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
✅ Cross-SDK Consistency ReviewI've reviewed this PR for consistency across all four SDK implementations (Node.js/TypeScript, Python, Go, and .NET). The changes successfully maintain feature parity and consistent API design. Summary of ChangesThis PR adds experimental API annotations across all SDKs by:
Consistency Analysis✅ Consistent Implementation Across All Languages
Language-Specific Implementation DetailsC# (most sophisticated):
TypeScript:
Python:
Go:
✅ Redundancy Avoidance LogicAll four languages correctly implement the same "skip method annotation when group is fully experimental" logic:
This prevents redundant annotations (e.g., if ConclusionNo consistency issues found. This PR exemplifies excellent cross-SDK development:
The implementation respects each language's idioms while maintaining conceptual consistency. Great work! 🎉
|
Summary
The
api.schema.jsonfrom the@github/copilotnpm package includes a"stability": "experimental"field on certain RPC methods, but none of the code generators were reading or using it. This PR propagates those markers into the generated SDK code across all four languages.Experimental APIs annotated
session.fleet.startsession.agent.listsession.agent.getCurrentsession.agent.selectsession.agent.deselectsession.compaction.compactWhat's annotated
Three levels of annotation are applied:
FleetApi,AgentApi,CompactionApi)SessionFleetStartResult,SessionFleetStartRequest)Language-specific annotations
[Experimental(Diagnostics.Experimental)][Experimental(Diagnostics.Experimental)][Experimental(Diagnostics.Experimental)](only if group is mixed)/** @experimental *//** @experimental *//** @experimental */(only if group is mixed)# Experimental:comment# Experimental:comment// Experimental:comment// Experimental:comment// Experimental:comment (only if group is mixed)C# details
Diagnostics.Experimentalinternal const ("GHCP001") is generated inRpc.csand referenced by all[Experimental]attributesGHCP001internally (the SDK must construct its own experimental types); consumers still see the warningGHCP001so tests can exercise experimental APIsFiles changed
Codegen scripts (
scripts/codegen/):utils.ts—stability?: stringonRpcMethod,isNodeFullyExperimental()helpercsharp.ts,typescript.ts,python.ts,go.ts— read stability, emit annotationsGenerated files:
dotnet/src/Generated/Rpc.cs,nodejs/src/generated/rpc.ts,python/copilot/generated/rpc.py,go/rpc/generated_rpc.goProject files:
dotnet/src/GitHub.Copilot.SDK.csproj,dotnet/test/GitHub.Copilot.SDK.Test.csproj(NoWarn for GHCP001)