dennisdoomen / dennisdoomen/dotnet-library-starter-kit

[Feature]: Evaluate PublicApiAnalyzers as an alternative to the Verify-based API snapshots

Open
#112 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.