docs: add README guidance for experimental APIs#1123
Conversation
Rohan5commit
requested review from
ShivangiReja,
christothes,
joseharriaga and
jsquire
as code owners
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f3b40e830e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
Adds a new README section to explain how [Experimental] APIs in this SDK surface compiler warnings, which warning codes exist, and how to suppress them when warnings are treated as errors.
Changes:
- Adds an “Experimental APIs” subsection under Getting started → Prerequisites.
- Documents
OPENAI001/OPENAI002and shows a#pragma warningsuppression example.
| | `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area | | ||
| | `OPENAI002` | Realtime session types and session options | |
There was a problem hiding this comment.
The OPENAI001 row lists “realtime client entry points”, but RealtimeClient/OpenAIClient.GetRealtimeClient() are tagged [Experimental("OPENAI002")] (e.g., src/Generated/RealtimeClient.cs:15, src/Custom/OpenAIClient.cs:327). This is likely to mislead users about which warning they need to suppress; consider moving realtime client/entry points to the OPENAI002 row (or removing realtime from OPENAI001).
| | `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area | | |
| | `OPENAI002` | Realtime session types and session options | | |
| | `OPENAI001` | Assistants, vector stores, batches, evals, and other preview client surface area | | |
| | `OPENAI002` | Realtime client entry points, realtime session types, and session options | |
| | Warning code | Examples of affected API areas | | ||
| | --- | --- | | ||
| | `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area | | ||
| | `OPENAI002` | Realtime session types and session options | | ||
|
|
||
| If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning in the narrowest possible scope: |
There was a problem hiding this comment.
This section enumerates experimental warning codes, but the public API also uses other [Experimental] diagnostic IDs like SCME0002 (e.g., settings/DI entry points in src/Custom/*ClientSettings.cs). Either include these in the table or clarify that the table is specifically for OpenAI-defined OPENAI### warnings so users aren’t confused when they encounter SCME0002.
| | Warning code | Examples of affected API areas | | |
| | --- | --- | | |
| | `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area | | |
| | `OPENAI002` | Realtime session types and session options | | |
| If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning in the narrowest possible scope: | |
| The table below lists the OpenAI-defined experimental warning codes (`OPENAI###`) used by this library. Some public APIs may also carry other `[Experimental]` diagnostic IDs from shared infrastructure or supporting packages, such as `SCME0002`. | |
| | Warning code | Examples of affected API areas | | |
| | --- | --- | | |
| | `OPENAI001` | Assistants, vector stores, batches, evals, realtime client entry points, and other preview client surface area | | |
| | `OPENAI002` | Realtime session types and session options | | |
| If your project treats warnings as errors, experimental APIs can fail the build until you suppress the relevant warning code for the API you are using in the narrowest possible scope: |
| ### Experimental APIs | ||
|
|
There was a problem hiding this comment.
The README Table of Contents includes “Prerequisites” and then “Install the NuGet package”, but this new “Experimental APIs” subsection isn’t listed. Consider adding it under “Getting started” in the TOC so the new guidance is discoverable.
|
|
||
| ### Experimental APIs | ||
|
|
||
| Some APIs in this library are marked with `[Experimental]` while the corresponding service surface is still evolving. When you use one of these types or members, the compiler emits a warning code so you can opt in deliberately. |
There was a problem hiding this comment.
... service surface is still evolving is not quite correct. The intent of [Experimental] is to denote that the client API surface is evolving. It has no connection to the state of the service.
If you'd be so kind, can we revise a bit to something like:
What's Experimental used for?
Experimental is used to designate that the client API surface is still undergoing iteration and should be expected to change, potentially in ways that are breaking. This may include both compile-time and behavioral changes in the client API. To acknowledge this risk, .NET requires that you opt-into experimental features by suppressing the warning in whatever way you prefer.
Once a client API reaches a stable state (no longer tagged experimental) then it is covered by a strong backwards compatibility guarantee. We will not make binary breaking changes and will only make disruptive behavioral changes when there is a critical need, such as patching a security vulnerability.
What Experimental isn't
-
Client use of
Experimentaldoes not communicate any message about the feature in the REST API. The OpenAI platform docs are the authoritative source for that information. -
Client use of
Experimentaldoes not communicate any message about the quality or reliability of the feature. We believe that all client features that we release meet our quality bar and are safe and reliable to use in production environments. -
Client use of
Experimentaldoes not communicate any message about supportability of the feature. We support all released client features when used with the official OpenAI service.
Summary
Related issue
Guideline alignment
Validation
git diff --check