.NET: Set up PublicAPI analyzers and shipped API promotion

[baywet]

Summary

The .NET projects currently do not appear to use Microsoft.CodeAnalysis.PublicApiAnalyzers or PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt baselines. We should consider setting them up for released packages so public API changes are explicitly reviewed, tracked, and promoted as part of the release process.

Proposal

1. Add Public API Analyzer support to released .NET packages.

   • Add the analyzer package/configuration needed to enforce public API baselines.
   • Add PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt files for packages that publish public APIs.
   • Establish guidance for contributors: new public APIs go into PublicAPI.Unshipped.txt; breaking/removal changes are intentional and reviewed.

2. Add an automatic shipped API promotion workflow.

   • Use a workflow similar to microsoft/OpenAPI.NET's promote-shipped-apis.yml: https://github.com/microsoft/OpenAPI.NET/blob/main/.github/workflows/promote-shipped-apis.yml
   • On pushes to release branches and/or manual dispatch, move entries from PublicAPI.Unshipped.txt to PublicAPI.Shipped.txt and open/update a PR.
   • This keeps API baselines current without making release managers manually promote each entry.

3. Update release workflows to fail when unshipped public API entries remain.

   • Before publishing packages, validate that PublicAPI.Unshipped.txt files are empty or absent.
   • This prevents releasing packages with APIs that were added but never promoted into the shipped baseline.

Benefits

• Makes public API changes visible in PRs instead of relying on reviewers to notice new public types, members, constants, or accessibility changes.
• Helps distinguish intentional API additions from accidental public surface area exposure.
• Creates an auditable history of shipped APIs for released packages.
• Makes release readiness clearer by separating unshipped API work from APIs that have been accepted into the shipped contract.
• Reduces reviewer burden when public APIs are added across multiple projects or target frameworks.

Risks addressed

• Accidentally shipping new public APIs without design/API review.
• Accidentally changing or removing public APIs in ways that may break consumers.
• Forgetting to promote accepted APIs before release.
• Inconsistent API baseline practices across packages.
• Discovering API-surface problems late in the release pipeline instead of during PR validation.

Notes

This is especially useful for released packages where even small additions, such as public constants used as metadata keys, become part of the supported surface area once published.

[SergeyMenshykh]

Both SK and MAF use the same .NET package validation mechanism to detect breaking API changes. It compares a newly built package’s public API with a configured baseline version previously published on NuGet.

[baywet]

Thank you for the additional information.

I didn't notice package validation setup. While they overlap on some aspects, they look at slightly different things. Here is a list of things the PublicAPIAnalyzers would add, that's not already being validated:

• Accidental public API exposure validation
• Nullability changes tracking
• Runs a build time (package validation only runs at pack)
• Guards against source breaking changes (package validation guards against binary breaking changes)