dennisdoomen / dennisdoomen/dotnet-library-starter-kit
[Feature]: Evaluate PublicApiAnalyzers as an alternative to the Verify-based API snapshots
- Dominant language
- C#
- Stars
- 77
- Forks
- 5
- PR merge metrics
- No merged PRs in 30d
Description
### Background and motivation
The templates catch unintended public API changes with Verify snapshots, which run as a test. [`Microsoft.CodeAnalysis.PublicApiAnalyzers`](https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) does something similar, but as an analyzer: it reports the change as a compiler error the moment you type it, with a code fix that adds the new member to `PublicAPI.Unshipped.txt`.
It also distinguishes shipped from unshipped API, which is genuinely useful when deciding what a release may still change.
Proposal: evaluate adding it, either alongside the Verify snapshots or as an alternative that users can choose.
### Alternative Concerns
* This clearly overlaps with the existing `ApiVerificationTests` project (#57). Running both means maintaining two sets of API files, which is likely more annoying than useful, so this may well be an either/or decision rather than an addition.
* The Verify approach has the advantage of showing the API per target framework, which the analyzer does not do as neatly.
* The analyzer's advantage is speed of feedback: you learn about it while typing, not after running a test.
Given the overlap, the honest outcome of this issue might be "no", but it is worth writing down the reasoning so it does not keep coming up.
### Could you help with a pull-request?
No
Contributor guide
Research direction
Start by reviewing the existing ApiVerificationTests project referenced in issue #57 and the Microsoft.CodeAnalysis.PublicApiAnalyzers documentation linked in the issue. Compare the Verify snapshots with PublicAPI.Unshipped.txt and target-framework behavior, then document whether the analyzer should be added, offered as an alternative, or rejected and why.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100