ASP.NET Core team how to track API change?

[Li7ye]

I'm a framework developer. Whenever a new version is released, there are new APIs or breaking change APIs. I used to record them manually, and I haven't found an existing tool that can directly generate them (such as md file). So I want to know: how does the ASP.NET Core team track API changes? thx

[wellkilo]

ASP.NET Core tracks the public surface as checked-in API baselines and enforces them during the build; it is not maintained only as a release-time Markdown list.

For each shipping implementation project, the relevant files are:

PublicAPI.Shipped.txt
PublicAPI.Unshipped.txt

The repository's docs/APIBaselines.md defines the lifecycle:

• PublicAPI.Shipped.txt represents APIs shipped in the previous major version.
• PublicAPI.Unshipped.txt records additions and removals since that baseline.
• A new API adds its signature to Unshipped.
• A removal adds a *REMOVED*... entry.
• A signature/nullability change is represented as removal of the old signature plus addition of the new one.

The enforcement comes from Microsoft.CodeAnalysis.PublicApiAnalyzers. CSharp.Common.targets enables it by default for implementation projects, so an unrecorded public API change produces analyzer/build errors such as RS0016. The normal contributor workflow is to use the analyzer code fix (“Add ... to public API”), rebuild, and commit the resulting baseline diff with the implementation.

At the major-version boundary, the build team runs eng/scripts/mark-shipped.ps1. It merges additions from Unshipped into Shipped, applies *REMOVED* entries, sorts/deduplicates the result, and resets Unshipped. CodeCheck.ps1 also prevents inappropriate baseline edits on frozen/release branches.

For another framework, the reusable design is therefore:

1. Generate a normalized public API signature file per package/assembly.
2. Keep separate shipped and current-cycle baselines in Git.
3. Compare source/assemblies with the baseline in CI.
4. Require every addition, removal, and signature change to appear in the PR diff.
5. Roll the current-cycle file into the shipped baseline only at a release boundary.

That gives you machine-enforced API tracking. It does not automatically produce human-facing release notes: those still need categorization and explanation, but the baseline diff is a reliable input from which a Markdown report can be generated.

If this answers how the ASP.NET Core repository does it, please mark it as the accepted answer.

[Li7ye]

@wellkilo thx