[APICompat] Document newly added features

[ViktorHofer]

TODO:

• [ ] Document the msbuild properties that are expected to be set and are passed onto the ValidatePackage task.
• [ ] Document the ValidateAssemblies task and its parameters
• [ ] Document the Microsoft.DotNet.ApiCompat.Tool global tool and its parameters
• [ ] Document the added rules // cc @smasher164
• [ ] Consider grouping the existing PackageValidation documentation under a new APICompat section

[ghost]

@dotnet/area-infrastructure-libraries a new issue has been filed in the ApiCompat area, please triage

[ViktorHofer]

The target date for this is October 10th, to make sure that documentation is in place when RC2 releases publicly.

[ericstj]

Dropping some notes: https://github.com/dotnet/docs/tree/main/docs/fundamentals/package-validation is a place to put the docs. Consider predent from SDK tools / properties to see how to document this.

[carlossanlop]

I opened https://github.com/dotnet/docs/issues/36235 so the Docs Content Team can update the page.

[gewarren]

Can you give me any more info that I can use to make these documentation updates - e.g. what are the new MSBuild properties?

For the diagnostic IDs, I'm not seeing any here that haven't already been documented.

[ViktorHofer]

Sure. All the properties/items that don't start with an underscore are "public" and should be documented:

• https://github.com/dotnet/sdk/blob/5cea8bc6d610c62f57320599954c6eeae52c077e/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.ApiCompat.ValidatePackage.targets#L28-L30
• https://github.com/dotnet/sdk/blob/main/src/Tasks/Microsoft.NET.Build.Tasks/targets/Microsoft.NET.ApiCompat.ValidatePackage.targets#L39-L59

We shouldn't document the following ones:

• RunApiCompat
• RuntimeIdentifierGraphPath

We should mention that individual diagnostic ids can be suppressed via suppression files or via NoWarn either per package or globally.

[gewarren]

I think this issue can be closed now.

[ViktorHofer]

Closing in favor of https://github.com/dotnet/docs/issues/36235. The work for this is nearly completed. Just waiting for https://github.com/dotnet/docs/pull/38533 to get merged.