Add a public-API break guard (Roslyn PublicApiAnalyzers) to the consumer-facing assemblies#530
Draft
ChrisonSimtian wants to merge 2 commits into
Draft
Add a public-API break guard (Roslyn PublicApiAnalyzers) to the consumer-facing assemblies#530ChrisonSimtian wants to merge 2 commits into
ChrisonSimtian wants to merge 2 commits into
Conversation
Adds Microsoft.CodeAnalysis.PublicApiAnalyzers and an opt-in mechanism in Directory.Build.props (_FalloutPublicApiAssemblies): each listed assembly gets the analyzer plus its PublicAPI.Shipped/Unshipped.txt as AdditionalFiles. Guard severities: - RS0016 (public surface not recorded in the API files) -> error via .editorconfig, which also lets [*.Generated.cs] switch it off for the generated tool wrappers. - RS0017 (a recorded entry removed/renamed) -> error via WarningsAsErrors, because it anchors to the PublicAPI.*.txt additional file where per-file editorconfig severity can't reach it. RS0016 is deliberately kept OUT of WarningsAsErrors: a command-line /warnaserror would outrank the per-file suppression and re-promote the whole generated surface. - Advisory rules (RS0026/RS0027/RS0036/RS0037) are off. Generated tool wrappers are excluded because that surface is regenerated from the *.json specs and is already contract-guarded by the SourceGenerators Verify snapshots. This is the guard that would have failed CI on the #257 SolutionModel -> Solution rename. Phased rollout: Fallout.Build, Fallout.Tooling and Fallout.Utilities follow in a fast follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Records the current shipped public API of the 11 opted-in consumer-facing assemblies (hand-written surface only; generated tool wrappers excluded). Empty Unshipped.txt files hold future additions until the next release rolls them into Shipped.txt. Generated by building each assembly against empty API files and recording the reported RS0016 signatures; all 11 round-trip to a clean build, and both guard directions (RS0016 on add/rename, RS0017 on remove) were verified to break the build. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ChrisonSimtian
added
enhancement
Collaborator
Author
|
@dennisdoomen thats what it would look like |
Collaborator
|
What about using |
Collaborator
Required more plumbing than I expected. But looks neat.
Me and @ChrisonSimtian discussed this. We want to see how the Roslyn analyzer handles this. |
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
3 participants
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.
PR B of the #257 follow-up. A build-breaking guard on the public API surface, so a future rename/removal like the
SolutionModel → Solutionmove (#257) fails CI instead of shipping silently. Non-breaking / additive (dev-infra only).What it does
Microsoft.CodeAnalysis.PublicApiAnalyzersinto 11 consumer-facing assemblies via an opt-in list (_FalloutPublicApiAssemblies) inDirectory.Build.props. Each records its surface in committedPublicAPI.Shipped.txt(Unshipped.txtholds future additions)..editorconfig.WarningsAsErrors— it anchors to the API text file, where per-file editorconfig severity can't reach it.Deliberate scoping
*.Generated.cs) excluded. ~60k of the RS0016 hits were generated tool surface; it's regenerated from the*.jsonspecs and already contract-guarded by the SourceGenerators Verify snapshots. Excluded via.editorconfig; RS0016 is kept out ofWarningsAsErrorsso a command-line/warnaserrorcan't outrank that per-file suppression.Fallout.Solutions.SolutionAttributethat feat(persistence)!: inline vs-solutionpersistence; rename SolutionModel → Solution; namespace cleanup #257 moved) + Core, Components, ProjectModel, Solution, Build.Shared and the small Utilities.* assemblies. Mid-size Fallout.Build, Fallout.Tooling, Fallout.Utilities follow in a fast follow-up.Baselines
~2,565 API lines across 11 assemblies (Common 2,239; Components 145; Solution 46; Net 39; Core 28; others small). Generated by recording each assembly's RS0016 signatures against empty API files.
Test plan
dotnet build fallout.slnxgreen (0 errors)