feat(analyzers): improve diagnostic guidance - #10832
Merged
ReubenBond merged 2 commits intoAug 26, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves Orleans analyzer and contract-manifest guidance by (1) recording convention-derived GrainType/GrainInterfaceType identities in OrleansContracts.txt, and (2) adding stable, per-diagnostic documentation pages and wiring analyzer helpLinkUri values to an aka.ms redirect so IDE help links remain stable over time.
Changes:
- Update the contract compatibility analyzer/code fix pipeline to write effective
GrainType/GrainInterfaceTypevalues and to normalize away generated manifest headers. - Add a test ensuring every analyzer diagnostic exposes a stable help link (
https://aka.ms/orleans/diagnostics#orleans####). - Add a diagnostics documentation index and per-diagnostic reference pages (including legacy
ORLEANS0003) and link them from the docs ToC.
Show a summary per file
| File | Description |
|---|---|
| test/Orleans.Analyzers.Tests/GrainInterfaceVersionAnalyzerTest.cs | Adds coverage for convention-based identities and header removal behavior in contract code fixes. |
| test/Orleans.Analyzers.Tests/DiagnosticHelpLinkTests.cs | Verifies all analyzer descriptors expose stable help links. |
| src/Orleans.Transactions/OrleansContracts.txt | Records effective GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Transactions.TestKit.Base/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.TestingHost/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Streaming/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Runtime/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Reminders/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Persistence.Memory/OrleansContracts.txt | Records effective GrainType values in the checked-in manifest. |
| src/Orleans.EventSourcing/OrleansContracts.txt | Records effective GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.DurableJobs/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Core/OrleansContracts.txt | Records effective GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Core.Abstractions/OrleansContracts.txt | Records effective GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.BroadcastChannel/OrleansContracts.txt | Records effective GrainInterfaceType values in the checked-in manifest. |
| src/Dashboard/Orleans.Dashboard/OrleansContracts.txt | Records effective GrainType/GrainInterfaceType values in the checked-in manifest. |
| src/Orleans.Analyzers/Constants.cs | Adds a shared helper to generate stable analyzer help-link URIs. |
| src/Orleans.Analyzers/AlwaysInterleaveDiagnosticAnalyzer.cs | Sets helpLinkUri for ORLEANS0001 via the stable helper. |
| src/Orleans.Analyzers/NoRefParamsDiagnosticAnalyzer.cs | Sets helpLinkUri for ORLEANS0002 via the stable helper. |
| src/Orleans.Analyzers/ConfigureAwaitAnalyzer.cs | Sets helpLinkUri for ORLEANS0014 via the stable helper. |
| src/Orleans.Analyzers/GrainInterfacePropertyDiagnosticAnalyzer.cs | Sets helpLinkUri for ORLEANS0008 via the stable helper. |
| src/Orleans.Analyzers/GrainInterfaceMethodReturnTypeDiagnosticAnalyzer.cs | Sets helpLinkUri for ORLEANS0009/ORLEANS0026 via the stable helper. |
| src/Orleans.Analyzers/GenerateAliasAttributesAnalyzer.cs | Sets helpLinkUri for ORLEANS0010 via the stable helper. |
| src/Orleans.Analyzers/IdClashAttributeAnalyzer.cs | Sets helpLinkUri for ORLEANS0012 via the stable helper. |
| src/Orleans.Analyzers/AliasClashAttributeAnalyzer.cs | Sets helpLinkUri for ORLEANS0011 via the stable helper. |
| src/Orleans.Analyzers/IncorrectAttributeUseAnalyzer.cs | Sets helpLinkUri for the incorrect-attribute-use diagnostic via the stable helper. |
| src/Orleans.Analyzers/AtMostOneOrleansConstructorAnalyzer.cs | Sets helpLinkUri for constructor-related diagnostics via the stable helper. |
| src/Orleans.Analyzers/AbstractPropertiesCannotBeSerializedAnalyzer.cs | Sets helpLinkUri for serialization member-shape diagnostics via the stable helper. |
| src/Orleans.Analyzers/GenerateSerializationAttributesAnalyzer.cs | Sets helpLinkUri for missing-serialization-attributes diagnostics via the stable helper. |
| src/Orleans.Analyzers/GenerateGenerateSerializerAttributeAnalyzer.cs | Sets helpLinkUri for missing-GenerateSerializer diagnostics via the stable helper. |
| src/Orleans.Analyzers/GrainInterfaceVersionAnalyzer.cs | Adds helpLinkUri for contract diagnostics and updates identity derivation logic. |
| src/Orleans.Analyzers/GrainInterfaceVersionCodeFix.cs | Updates code fixes to write effective identities and drop/normalize generated headers. |
| docs/site/src/content/docs/toc.yml | Adds an “Analyzer diagnostics” section linking to the new diagnostics index and pages. |
| docs/site/src/content/docs/grains/grain-versioning/contract-compatibility-analyzer.md | Updates documentation to reflect effective identity recording and links diagnostics to the new pages. |
| docs/site/src/content/docs/diagnostics/index.md | Adds a diagnostics landing/index page and explains the stable aka.ms help-link strategy. |
| docs/site/src/content/docs/diagnostics/orleans0001.md | Adds per-diagnostic reference documentation for ORLEANS0001. |
| docs/site/src/content/docs/diagnostics/orleans0002.md | Adds per-diagnostic reference documentation for ORLEANS0002. |
| docs/site/src/content/docs/diagnostics/orleans0003.md | Adds legacy per-diagnostic reference documentation for removed ORLEANS0003. |
| docs/site/src/content/docs/diagnostics/orleans0004.md | Adds per-diagnostic reference documentation for ORLEANS0004. |
| docs/site/src/content/docs/diagnostics/orleans0005.md | Adds per-diagnostic reference documentation for ORLEANS0005. |
| docs/site/src/content/docs/diagnostics/orleans0006.md | Adds per-diagnostic reference documentation for ORLEANS0006. |
| docs/site/src/content/docs/diagnostics/orleans0007.md | Adds per-diagnostic reference documentation for ORLEANS0007. |
| docs/site/src/content/docs/diagnostics/orleans0008.md | Adds per-diagnostic reference documentation for ORLEANS0008. |
| docs/site/src/content/docs/diagnostics/orleans0009.md | Adds per-diagnostic reference documentation for ORLEANS0009. |
| docs/site/src/content/docs/diagnostics/orleans0010.md | Adds per-diagnostic reference documentation for ORLEANS0010. |
| docs/site/src/content/docs/diagnostics/orleans0011.md | Adds per-diagnostic reference documentation for ORLEANS0011. |
| docs/site/src/content/docs/diagnostics/orleans0012.md | Adds per-diagnostic reference documentation for ORLEANS0012. |
| docs/site/src/content/docs/diagnostics/orleans0013.md | Adds per-diagnostic reference documentation for ORLEANS0013. |
| docs/site/src/content/docs/diagnostics/orleans0014.md | Adds per-diagnostic reference documentation for ORLEANS0014. |
| docs/site/src/content/docs/diagnostics/orleans0016.md | Adds per-diagnostic reference documentation for ORLEANS0016. |
| docs/site/src/content/docs/diagnostics/orleans0017.md | Adds per-diagnostic reference documentation for ORLEANS0017. |
| docs/site/src/content/docs/diagnostics/orleans0018.md | Adds per-diagnostic reference documentation for ORLEANS0018. |
| docs/site/src/content/docs/diagnostics/orleans0019.md | Adds per-diagnostic reference documentation for ORLEANS0019. |
| docs/site/src/content/docs/diagnostics/orleans0020.md | Adds per-diagnostic reference documentation for ORLEANS0020. |
| docs/site/src/content/docs/diagnostics/orleans0021.md | Adds per-diagnostic reference documentation for ORLEANS0021. |
| docs/site/src/content/docs/diagnostics/orleans0022.md | Adds per-diagnostic reference documentation for ORLEANS0022. |
| docs/site/src/content/docs/diagnostics/orleans0023.md | Adds per-diagnostic reference documentation for ORLEANS0023. |
| docs/site/src/content/docs/diagnostics/orleans0024.md | Adds per-diagnostic reference documentation for ORLEANS0024. |
| docs/site/src/content/docs/diagnostics/orleans0025.md | Adds per-diagnostic reference documentation for ORLEANS0025. |
| docs/site/src/content/docs/diagnostics/orleans0026.md | Adds per-diagnostic reference documentation for ORLEANS0026. |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 59/59 changed files
- Comments generated: 1
- Review effort level: Lite
Comment on lines
490
to
495
| _visitedClasses.TryAdd(declaredClass.Name, true); | ||
| if (string.Equals(codeAlias, declaredClass.Alias, StringComparison.Ordinal)) | ||
| if (declaredClass.Alias is null | ||
| || string.Equals(codeAlias, declaredClass.Alias, StringComparison.Ordinal)) | ||
| { | ||
| return; | ||
| } |
Contributor
Code coverage77.61% line coverage - 97,576 / 125,722 lines Coverage details
|
This was referenced Aug 28, 2026
Merged
This was referenced Sep 1, 2026
This was referenced Sep 8, 2026
Open
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.
Problem
OrleansContracts.txtdid not show convention-derived grain and interface identities, so contract diffs could not clearly distinguish safe CLR renames from breaking Orleans identity changes. The manifest also needed clear generated-file guidance, and analyzer diagnostics lacked stable, actionable documentation links.Solution
GrainTypeandGrainInterfaceTypevalues in generated and checked-in contract manifests.https://aka.ms/orleans/OrleansContracts.txtfor regeneration instructions.ORLEANS0003rule for older packages.https://aka.ms/orleans/diagnostics#orleans####so IDE users can open the relevant guidance.Rationale
The manifest now makes identity-preserving and identity-breaking changes apparent during review and directs maintainers to a repeatable update workflow. Stable diagnostic links provide current guidance for impact, remediation, code fixes, and suppression without coupling released analyzer packages to the documentation site's physical URL structure.