diff --git a/docs/APIBaselines.md b/docs/APIBaselines.md index f44598af9b86..75a94caef6cd 100644 --- a/docs/APIBaselines.md +++ b/docs/APIBaselines.md @@ -1,13 +1,17 @@ # API Baselines -This document contains information regarding API baseline files and how to work with them. +This document contains information regarding API baseline files and how to work with them. For additional details on how these files works, consult: +- https://github.com/dotnet/roslyn-analyzers/blob/master/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md +- https://github.com/dotnet/roslyn-analyzers/blob/master/src/PublicApiAnalyzers/Microsoft.CodeAnalysis.PublicApiAnalyzers.md ## Add baseline files for new projects When creating a new implementation (i.e. src) project, it's necessary to manually add API baseline files since API baseline are enabled by default. If the project is a non-shipping or test only project, add `false` to the project to disable these checks. To add baseline files to the project: -1. Copy eng\PublicAPI.empty.txt to the project directory and rename it to PublicAPI.Shipped.txt -1. Copy eng\PublicAPI.empty.txt to the project directory and rename it to PublicAPI.Unshipped.txt +1. `cp .\eng\PublicAPI.empty.txt {new folder}\PublicAPI.Shipped.txt` +1. `cp .\eng\PublicAPI.empty.txt {new folder}\PublicAPI.Unshipped.txt` + +See [Steps for adding and updating APIs](#steps-for-adding-and-updating-apis) for steps on how to add APIs to the Unshipped.txt files ## PublicAPI.Shipped.txt @@ -15,7 +19,7 @@ This file contains APIs that were released in the last major version. This file ## PublicAPI.Unshipped.txt -This file contains new APIs since the last major version. +This file contains new APIs since the last major version. Steps for working with changes in APIs and updating this file are found in [Steps for adding and updating APIs](#steps-for-adding-and-updating-apis). ### New APIs @@ -45,6 +49,21 @@ Two new entry needs to be added to the PublicAPI.Unshipped.txt file for an updat Microsoft.AspNetCore.DataProtection.Infrastructure.IApplicationDiscriminator.Discriminator.get -> string? ``` +### Steps for adding and updating APIs + +1. Update AspNetCore.sln and relevant `*.slnf` file to include the new project if needed +1. `{directory containing relevant *.slnf}\startvs.cmd` +1. F6 *or whatever your favourite build gesture is* +1. Click on a RS0016 (or whatever) error +1. Right click in editor on underscored symbol or go straight to the “quick fix” icon to its left. Control-. also works. +1. Choose “Add Blah to public API” / “Fix all occurrences in … Solution” +1. Click Apply +1. F6 *again to see if the fixer missed anything or if other RS00xx errors show up (not uncommon)* +1. Suppress or fix other problems as needed but please suppress (if suppressing) using attributes and not globally or with `#pragma`s because attributes make the justification obvious e.g. for common errors that can't be fixed + `[SuppressMessage("ApiDesign", "RS0026:Do not add multiple public overloads with optional parameters", Justification = "Required to maintain compatibility")]` + or + `[SuppressMessage("ApiDesign", "RS0027:Public API with optional parameter(s) should have the most parameters amongst its public overloads.", Justification = "Required to maintain compatibility")]` + ## Updating baselines after major releases -TODO \ No newline at end of file +This will be performed by the build team using scripts at https://github.com/dotnet/roslyn/tree/master/scripts/PublicApi (or an Arcade successor). The process moves the content of PublicAPI.Unshipped.txt into PublicAPI.Shipped.txt diff --git a/eng/scripts/CodeCheck.ps1 b/eng/scripts/CodeCheck.ps1 index 078c34bc9ad8..3c196f775782 100644 --- a/eng/scripts/CodeCheck.ps1 +++ b/eng/scripts/CodeCheck.ps1 @@ -191,18 +191,27 @@ try { } } - Write-Host "Checking for changes to API baseline files" + $targetBranch = $env:SYSTEM_PULLREQUEST_TARGETBRANCH + if ($targetBranch.StartsWith('refs/heads/')) { + $targetBranch = $targetBranch.Replace('refs/heads/','') + } # Retrieve the set of changed files compared to main - $commitSha = git rev-parse HEAD - $changedFilesFromMain = git --no-pager diff origin/main...$commitSha --ignore-space-change --name-only --diff-filter=ar + Write-Host "Checking for changes to API baseline files $targetBranch" + + $changedFilesFromTarget = git --no-pager diff origin/$targetBranch --ignore-space-change --name-only --diff-filter=ar $changedAPIBaselines = [System.Collections.Generic.List[string]]::new() - if ($changedFilesFromMain) { - foreach ($file in $changedFilesFromMain) { + if ($changedFilesFromTarget) { + foreach ($file in $changedFilesFromTarget) { + # Check for changes in Shipped in all branches if ($file -like '*PublicAPI.Shipped.txt') { $changedAPIBaselines.Add($file) } + # Check for changes in Unshipped in servicing branches + if ($targetBranch -like 'release*' -and $file -like '*PublicAPI.Unshipped.txt') { + $changedAPIBaselines.Add($file) + } } }