Teaches ApiCompat about the Experimental attribute - #55617
Open
JoeRobich wants to merge 1 commit into
Open
Conversation
|
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. |
Contributor
There was a problem hiding this comment.
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
DifferenceSeverityand plumb symbol context intoCompatDifferenceso 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 fromAttributesMustMatch.
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
Comment on lines
+18
to
+28
| #if IncludeExperimentalApis | ||
| [System.Diagnostics.CodeAnalysis.Experimental("TEST001")] | ||
| public string ExperimentalRemoved(string name) => $"Experimental goodbye, {name}!"; | ||
|
|
||
| [System.Diagnostics.CodeAnalysis.Experimental("TEST002")] | ||
| public string Promoted(string name) => $"Promoted hello, {name}!"; | ||
| #endif | ||
|
|
||
| #if IncludeStablePromotedApi | ||
| public string Promoted(string name) => $"Promoted hello, {name}!"; | ||
| #endif |
Comment on lines
+18
to
21
| public readonly struct CompatDifference(MetadataInformation left, MetadataInformation right, string diagnosticId, string message, DifferenceType type, string? memberId, DifferenceSeverity severity = DifferenceSeverity.Error) : IDiagnostic, IEquatable<CompatDifference> | ||
| { | ||
| /// <inheritdoc /> | ||
| public string DiagnosticId { get; } = diagnosticId; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a new
DifferenceSeverity(Error/Informational) toCompatDifferenceand uses it so that ApiCompat no longer hard-fails on compatibility differences that are confined toSystem.Diagnostics.CodeAnalysis.ExperimentalAPIs. Instead:Experimentalon both sides (or was added/removed while experimental) are now logged as informational messages, not build errors, and are excluded from suppression-file generation.Experimental(i.e. "graduates" to stable), a new diagnosticCP0022(ExperimentalApiBecomesStable) is raised as an error, prompting the author to treat it as a new stable API requiring doc/review.AttributesMustMatchno longer double-reports theExperimentalattribute removal as a generic "attribute removed" diagnostic, since CP0022 already covers that transition.Resolves #50637