Skip to content

experimental-apis.md

Latest commit

 

History

History
57 lines (40 loc) · 3.12 KB

experimental-apis.md

File metadata and controls

57 lines (40 loc) · 3.12 KB
Raw

Experimental APIs

Fallout marks not-yet-stable public APIs with System.Diagnostics.CodeAnalysis.ExperimentalAttribute so consumers opt into instability deliberately. This page is the canonical registry of allocated FALLOUT0xx diagnostic IDs.

See ADR-0004 §5 for the decision and the agent conventions for the contributor rules.

How it works

An experimental API carries a diagnostic ID:

using System.Diagnostics.CodeAnalysis;

[Experimental("FALLOUT001")]
public sealed class NewPluginHost
{
    // ...
}

ExperimentalAttribute is an error-by-default diagnostic. Code that touches the API will not compile until you explicitly suppress the exact ID, which is your conscious opt-in to an API that may change without notice:

#pragma warning disable FALLOUT001 // opting into an experimental API
var host = new NewPluginHost();
#pragma warning restore FALLOUT001

or, project-wide, in your .csproj:

<PropertyGroup>
  <NoWarn>$(NoWarn);FALLOUT001</NoWarn>
</PropertyGroup>

Diagnostic-ID scheme

  • IDs use the form FALLOUT0xx and are allocated sequentially.
  • An ID is never reused — once retired it stays retired, so a suppression can never silently re-bind to a different API.
  • Every allocation is recorded in the registry table below, in the same PR that introduces the attribute.
  • Promoting an API to stable means deleting the [Experimental] attribute (the feature already rode the trunk — no cross-branch cherry-pick). The ID's row moves to Promoted status and the ID is retired, not recycled. Adding or removing [Experimental] is not a breaking change.
  • Channel discipline: on the main (preview) test lane the attribute is a courtesy; on a release/YYYY production line any risky-but-shipped public surface must wear it. (Since ADR-0008 main is the sole prerelease lane and the primary home for not-yet-stable surface, so gating it behind this attribute is what keeps the production cut clean.)

Registry

Status values: Experimental (live, opt-in), Promoted (attribute removed, now stable — ID retired), Withdrawn (API removed before promotion — ID retired).

ID Surface Introduced Status Notes
FALLOUT001 Fallout.Components.IPublish.PublishTargets / .PublishTo (multi-channel publishing) 2026.1 Experimental Fan a single Pack output across multiple feeds with per-feed package-ID routing (PublishTarget). Shape may change while the CD model firms up (epic #332). Promote by deleting the attribute once ReleaseChannel/DeploymentTarget (#334) settle.