microsoft / microsoft/typespec

Enhance @experimental with diagnostic IDs and dependencies

Open
#11,690 1 comment 1 reaction 0 assignees View on GitHub
emitter:client:csharp feature lib:http
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.