[JoeRobich]

Adds a new DifferenceSeverity (Error / Informational) to CompatDifference and uses it so that ApiCompat no longer hard-fails on compatibility differences that are confined to System.Diagnostics.CodeAnalysis.Experimental APIs. Instead:

• Differences where the affected API is Experimental on both sides (or was added/removed while experimental) are logged as informational messages, not build errors, and are excluded from suppression-file generation. Property and event accessors inherit the stability of their associated symbol.
• When an API stops being Experimental (i.e. "graduates" to stable), CP0022 (ExperimentalApiBecomesStable) is raised as an error, prompting the author to treat it as a new stable API requiring doc/review.
• When a stable API becomes Experimental, CP0023 (StableApiBecomesExperimental) is raised as an error because existing consumers will begin receiving compiler diagnostics.
• AttributesMustMatch routes Experimental additions and removals through these diagnostics regardless of strict mode, avoiding generic attribute diagnostics and duplicate reports.

Resolves #50637

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Updates ApiCompat’s compatibility reporting to recognize System.Diagnostics.CodeAnalysis.ExperimentalAttribute, downgrading differences confined to experimental APIs to informational output while introducing a new error diagnostic when an API “graduates” from experimental to stable.

Changes:

• Add DifferenceSeverity and plumb symbol context into CompatDifference so differences can be classified as Error vs Informational.
• Treat add/remove/modify differences as informational when the impacted API is experimental on both sides (or added/removed while experimental), and exclude such differences from suppression generation.
• Add rule/diagnostic CP0022 (ExperimentalApiBecomesStable) for the experimental → stable transition and avoid duplicate reporting from AttributesMustMatch.

Show a summary per file

File	Description
test/TestAssets/TestProjects/ApiCompatValidateAssembliesTestProject/Greeter.cs	Extends the test asset with experimental and promoted API shapes.
test/TestAssets/TestProjects/ApiCompatValidateAssembliesTestProject/ApiCompatValidateAssembliesTestProject.csproj	Adds MSBuild properties to drive new compilation symbols in the test asset.
test/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility.Tests/ExperimentalApiTests.cs	Adds unit coverage for experimental-difference severity and promotion behavior.
test/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompat.IntegrationTests/Tool/ApiCompatToolIntegrationTests.cs	Adds end-to-end CLI tests for experimental removals (pass) and promotions (fail + suppressible).
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.zh-Hant.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.zh-Hans.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.tr.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.ru.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.pt-BR.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.pl.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.ko.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.ja.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.it.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.fr.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.es.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.de.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/xlf/Resources.cs.xlf	Adds localization entry for ExperimentalApiBecomesStable.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Runner/ApiCompatRunner.cs	Uses severity to log experimental-only differences as messages instead of errors and to skip suppression generation for them.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Rules/RuleRunner.cs	Attaches left/right Roslyn symbols to differences produced during rule execution.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Rules/RuleFactory.cs	Registers the new ExperimentalApiBecomesStable rule in the default rule set.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Rules/ExperimentalApiBecomesStable.cs	Implements new CP0022 rule for experimental → stable transitions.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Rules/AttributesMustMatch.cs	Skips reporting “experimental attribute removed” to avoid duplicating CP0022.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Resources.resx	Adds the ExperimentalApiBecomesStable diagnostic message resource.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/DifferenceVisitor.cs	Downgrades differences to informational when the impacted API is experimental.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/DifferenceSeverity.cs	Adds DifferenceSeverity enum (Error/Informational).
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/DiagnosticIds.cs	Adds CP0022 diagnostic ID constant.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/CompatDifference.cs	Adds severity and symbol context to differences (used for classification and logging).
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/ApiStabilityClassifier.cs	Adds experimental/stable classification based on ExperimentalAttribute.
src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/ApiStability.cs	Adds stability enum used by the classifier.

Copilot's findings

• Files reviewed: 29/29 changed files
• Comments generated: 2

[JoeRobich]

@jeffhandley Could I get a review, assuming you are still the owner here. If not, can you please point me in the right direction?