Fixup API baselines after merge

[JunTaoLuo]

TODO:

• Restore Shipped API baseline files
• Update Unshipped API baseline files to match updated APIs
• Add documentation
• Add codecheck step to make sure no Shipped APIs are touched

[dougbu]

@JunTaoLuo did this get fixed elsewhere❔ Please fix the conflicts or close😃

[dougbu]

Good start apart from the conflicts 😁

[JunTaoLuo]

@dougbu would you like to update this section since you did it for 5.0 and have more expreience 😄

[dougbu]

In 5.0, I only had to copy files around because all PublicAPI.Shipped.txt files were empty. Fortunately a couple of scripts are available e.g. in the Roslyn repo. dotnet/roslyn-analyzers#3226 covers centralizing that work.

[wtgodbe]

Are these modified automatically during the build? Is there a way to automatically populate them? If not how should devs update them? Would be worth calling out in the doc

[dougbu]

Visual Studio is the only reliable way to update the files at the moment. Editing them manually is strongly discouraged because the syntax is finicky.

@Pilchie is working with the Roslyn team to enable dotnet format to handle this from the command line.

In the meantime, instructions for adding new implementation projects should mention

1. cp .\eng\PublicAPI.empty.txt {new folder}\PublicAPI.Shipped.txt
2. cp .\eng\PublicAPI.empty.txt {new folder}\PublicAPI.Unshipped.txt
3. Update AspNetCore.sln and relevant *.slnf file to include the new project
4. {directory containing relevant *.slnf}\startvs.cmd
5. F6 # or whatever your favourite build gesture is
6. Click on a RS0016 (or whatever) error
7. Right click in editor on underscored symbol or go straight to the “quick fix” icon to its left . Control-. also works.
8. Choose “Add Blah to public API” / “Fix all occurrences in … Solution”
9. Click Apply
10. F6 # yes, again to see if the fixer missed anything or if other RS00xx errors show up (not uncommon)
11. Suppress or fix other problems as needed but please suppress (if suppressing) using attributes and not globally or with #pragmas 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")]

More information available in

• 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

[wtgodbe]

Don't need to make the change now, but if there's a way to not hard-code the branch name that'd be preferable

[JunTaoLuo]

I'm not sure how we can remove the hard coding to the default branch, is there a git command to do that? In any case, I figured the default branch name shouldn't be modified often and I think in those cases, we would scrub the script for usages of the name anyway.

[dougbu]

There be dragons @JunTaoLuo In particular,

1. We need to enable a more drastic version of this in release/5.0, covering the PublicAPI.Unshipped.txt files too
   • We need to compare against release/5.0 there
2. Need to compare against our preview branches for 6.0 after each is split from main
3. This check will do nothing in rolling builds and should be suppressed unless $(Build.Reason) (in YAML) or $env:BUILD_REASON contain PullRequest

To get current branch in PR builds, can use

• git config --show-current displays the current branch name
• same information should be available in $(Build.SourceBranchName) in YAML or $env:BUILD_SOURCEBRANCHNAME
• use above w/o Name / NAME to get the full branch path but, with the name, should display the PR id

Need something like the GitHub REST API to get more information e.g. to display the base aka target branch

Invoke-WebRequest -Headers @{ Accept = "application/vnd.github.v3+json"} https://api.github.com/repos/dotnet/aspnetcore/pulls/{PR id} | `
 ConvertFrom-Json |ForEach-Object `
 base |ForEach-Object `
 ref

For internal PRs, the commands are probably like

Invoke-WebRequest  -Headers @{ Accept = "application/vnd.github.v3+json"} https://dev.azure.com/{blah}/{blah}/_git/dotnet-aspnetcore/_apis/git/pullrequests/{PR id}?api-version=5.0 |ForEach-Object `
  targetRefName

But, I don't see documentation on how to authenticate nor control the preferred response type. (May respond w/ JSON in successful cases but I'm only getting 404s despite testing w/ an existing PR.)

@ilyas1974 anyone in your world with the AzDO REST API knowledge we need❔ Note we'd like to run this in CI, where we should have the right tokens available.

[dougbu]

Suepct we'd be fine w/ a translation of https://docs.microsoft.com/en-us/rest/api/azure/devops/git/pull%20requests/get%20pull%20request%20by%20id?view=azure-devops-rest-5.0#security into English 😀

[JunTaoLuo]

The codecheck failure is expected since this PR needs to fix and restore APIBaseline.Shipped.txt files. In these cases, the admins need to override the failure and merge.

I'll follow up with improvements to the documentation separately.