microsoft / microsoft/typespec
Enhance @experimental with diagnostic IDs and dependencies
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
## Problem
`TypeSpec.HttpClient.@experimental` currently records only that a declaration is experimental and optionally scopes that metadata to emitters. Client emitters may also need:
- a stable diagnostic identifier to surface in generated APIs;
- the diagnostic identifiers of experimental features used by the generated implementation;
- an explicit way to represent composed experiments without silently graduating an API when a dependency changes.
For example, the C# emitter needs to generate an API shaped like:
```csharp
[Experimental("C")]
public void Bar()
{
#pragma warning disable A
#pragma warning disable B
// method body
#pragma warning restore A
#pragma warning restore B
}
```
Here, `C` is the public experiment and depends on experiments `A` and `B`.
## Proposal
Extend `FeatureLifecycleOptions` with optional `diagnosticId` and `dependsOn` fields:
```typespec
@experimental(#{
emitterScope: "@typespec/http-client-csharp",
diagnosticId: "C",
dependsOn: #["A", "B"]
})
op bar(): void;
```
### Semantics
- `diagnosticId` identifies the experiment surfaced on the generated public API.
- `dependsOn` identifies experimental features used by that API's generated implementation.
- Emitters decide how to represent this metadata. For C#, this maps to `ExperimentalAttribute` and scoped warning suppressions.
- Dependency graduation must **not** automatically remove the public API's experimental status. The API remains experimental until its `@experimental` decorator is explicitly removed.
- The existing lifecycle query should remain compatible, with a details API exposing the additional metadata.
## Acceptance criteria
- [ ] `@experimental` accepts optional `diagnosticId` and `dependsOn` values.
- [ ] Lifecycle metadata retrieval exposes the stage, diagnostic ID, and dependencies.
- [ ] Existing `getFeatureLifecycle` behavior remains unchanged.
- [ ] Emitter scoping applies to all lifecycle details.
- [ ] Documentation explains that graduation remains an explicit source change.
- [ ] The C# emitter can emit a public diagnostic and dependency suppressions from this metadata.
## Related work
- #11684
- #11685
Contributor guide
Research direction
Start by locating FeatureLifecycleOptions and the existing getFeatureLifecycle implementation, then trace lifecycle metadata through emitter scoping. Inspect the C# emitter and related documentation entry points. Done means optional diagnostic IDs and dependencies are retrievable without changing existing query behavior, documentation covers explicit graduation, and the C# emitter produces the requested diagnostic and suppression metadata.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- backend-api-design, compilers
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100