Enhance @experimental with diagnostic IDs and dependencies

[JoshLove-msft]

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:

[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:

@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

• Add diagnostic metadata to @experimental #11684
• Emit experimental diagnostics in C# clients #11685

[github-actions]

🎯 Issue Triage

Feature request to extend @experimental with optional diagnosticId and dependsOn fields in FeatureLifecycleOptions, enabling emitters (particularly C#) to surface stable public diagnostic identifiers and track implementation-level experiment dependencies.

Category: Feature Request

Area: emitter:client:csharp

🔍 Analysis

• The request adds two optional fields to the @experimental decorator: diagnosticId (stable identifier for the public API experiment) and dependsOn (list of implementation-level experiment IDs).
• The C# emitter use case requires emitting [Experimental("C")] on public APIs and #pragma warning disable A/B in method bodies — semantics that cannot be expressed with the current single-identifier model.
• The proposal preserves backward compatibility: existing getFeatureLifecycle behavior is unchanged, with a new details API exposing the extended metadata.
• Related issues: Add diagnostic metadata to @experimental #11684, Emit experimental diagnostics in C# clients #11685 (referenced in the issue body).
• Dependency graduation must not auto-graduate the public API's experimental status — this is an important semantic guardrail explicitly called out.

📝 Suggested next steps

• Review and discuss the proposed FeatureLifecycleOptions schema extension.
• Define the updated getFeatureLifecycle / details API surface.
• Implement the diagnosticId and dependsOn fields in the compiler/lifecycle library.
• Update the C# emitter to consume the new metadata (emit ExperimentalAttribute and pragma suppressions).
• Add documentation clarifying that graduation requires explicit source changes.

Generated by Agentic Triage