Public api analyzer [API-1573]

[zpqrtbnk]

This PR adds the Microsoft.CodeAnalysis.PublicApiAnalyzers analyzer to the Hazelcast.Net project. These analyzers maintain a signature of the complete public API exposed by the project, in a set of text files, and issue warnings whenever the current signature does not match the files.

This means that... if a public method or property or class or anything is changed, added, removed, anything - a warning will be logged in the build. This is used by the Roslyn team to monitor their API changes, and it willbe greatly beneficial to us to ensure compatibility between versions and track changes.

Note that the PR relies on a beta version of the analyzers that support merging multiple definition files (see PR#5422) and this is considered acceptable since it is a development-time dependency, and does not impact the production code in any ways.

How it works

Development

Covered projects (Hazelcast.Net at the moment) have an extra src/Hazelcast.Net/PublicAPI directory that contains a set of files. The PublicAPI.Shipped.txt files define the signature of the public API. Whenever that public API is modified, i.e. whenever the code does not match that signature anymore, RS0016 and other warnings appear during the build.

Whenever a change is made that is not a mistake, it should be added to PublicAPI.Unshipped.txt files. This will get rid of the warnings, but the change is still considered "proposed" and not "shipped" (see Release section below). Beware of conditional code (code within #if blocks) and their corresponding PublicAPI.Unshipped.txt files.

At one point of time, and before entering the release phase, the PublicAPI.Unshipped.txt should be carefully reviewed and merged into the PublicAPI.Shipped.txt files. Ideally these reviews should be independent PRs.

Release

When building a release/* branch, RS0016 and other warnings are escalated to errors (rule in AnalysisRules.prop) and therefore fail the build. In addition the hz.ps1 script looks for PublicAPI.Unshipped.txt files and fails the build in case some are detected.

A release build can therefore succeed only if changes to the public API have been reviewed, merged, etc.

Review

Open any public options file such as MetricsOptions and add a public property such as public int Whatever { get; set; }. Rebuild, ensure you see a new warning. Name the current branch release/foo and rebuild with hz.ps1 build, ensure the build fails.

Modify the PublicAPI.Unshipped.txt file to declare the new option. Rebuild, ensure the warning is one. Switch to release/foo and rebuild with hz.ps1, ensure the buid fails.

Merge the PublicAPI.Unshipped.txt changes into PublicAPI.Shipped.txt. Rebuild, ensure you see no warnings. Switch to release/foo and rebuild with hz.ps1, ensure the buid succeeds.

References

• https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md
• RS0017: No information on how to "remove" public API dotnet/roslyn-analyzers#5058
• https://github.com/dotnet/roslyn/blob/main/docs/Adding%20Optional%20Parameters%20in%20Public%20API.md#note
• https://github.com/dotnet/roslyn/blob/main/scripts/PublicApi/mark-shipped.ps1
• Quick action to move symbols from PublicApi.Unshipped.txt to PublicApi.Shipped.txt dotnet/roslyn-analyzers#3226
• Allow PublicAPI analyzers to merge from multiple sources dotnet/roslyn-analyzers#5422

[codecov-commenter]

Codecov Report

Merging #730 (c5fd6f3) into master (17f138a) will increase coverage by 0.18%.
The diff coverage is 98.08%.

@@            Coverage Diff             @@
##           master     #730      +/-   ##
==========================================
+ Coverage   83.41%   83.60%   +0.18%     
==========================================
  Files         862      872      +10     
  Lines       20113    20418     +305     
==========================================
+ Hits        16777    17070     +293     
- Misses       3336     3348      +12     

Impacted Files	Coverage Δ
...t.Net/Serialization/Compact/SchemaBuilderWriter.cs	100.00% <ø> (ø)
...et/Serialization/SerializationService.ReadWrite.cs	78.00% <45.45%> (-3.06%)	⬇️
src/Hazelcast.Net/Core/ConvertEx.cs	83.33% <83.33%> (ø)
...lization/Compact/CompactDictionaryGenericRecord.cs	96.66% <96.66%> (ø)
...ct/CompactDictionaryGenericRecord.GeneratedCode.cs	100.00% <100.00%> (ø)
.../Serialization/Compact/CompactGenericRecordBase.cs	100.00% <100.00%> (ø)
...mpact/CompactGenericRecordBuilder.GeneratedCode.cs	100.00% <100.00%> (ø)
...rialization/Compact/CompactGenericRecordBuilder.cs	100.00% <100.00%> (ø)
...lization/Compact/CompactGenericRecordSerializer.cs	100.00% <100.00%> (ø)
...n/Compact/CompactReaderExtensions.GeneratedCode.cs	100.00% <100.00%> (ø)
... and 13 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[emreyigit]

Looks nice.