d3c0f76ce6
Compute the API diff using the public (stable) NuGet instead of downloading custom zip files. Also remove all the legacy logic, and improve the README to explain the process. Note: the api diff won't work correctly in this PR (the comparison against the previous commit won't be correct, because the previous commit doesn't have the changes from this PR, which the new code expects). |
||
|---|---|---|
| .. | ||
| .gitignore | ||
| Makefile | ||
| README.md | ||
| merger.cs | ||
| report-status.sh | ||
README.md
New Releases
Inside Make.config update the STABLE_NUGET_VERSION_<platform>= line to point to the currently stable ref pack's NuGet version.
E.g. for the ref pack Microsoft.iOS.Ref.net8.0_17.5 with the version 17.5.8030 it would be this:
STABLE_NUGET_VERSION_iOS=net8.0_17.5/17.5.8030
New Revisions
On the bots each revision rebuilds every assemblies. Each of them will be compared to the downloaded stable version from the stable NuGet. Any changes (addition/removal) to the public API will be reported in HTML files.
This can be done manually with make. The .\diff\ directory will contain the diffs in HTML format.
The helper make merge target creates a single api-diff.html file (from all the diff\*.html files) that be used for the documentation web site.
Technical implementation
When comparing against the stable version of the ref pack NuGet, the process goes like this:
- Download the stable NuGet/nupkg (using a direct link, not 'dotnet restore', because we know exactly which version we need, so a direct link is both faster and less likely to fail).
a. Cache the nupkg locally if
MACIOS_CACHE_DOWNLOADS=1is set (the nupkg will be fetched from the cache instead if being downloaded if it exists in the cache) - Extract the reference assembly from the nupkg.
- Create an api description xml for the ref pack's ref assembly.
- Create an api description xml for the locally built ref assembly.
- Compare the two reference xml files, and write out the result, both in html and markdown.
- Create an api-diff.html file that summarizes the comparison result.
When comparing against a different commit (using the tools/compare-commits.sh script), the script will change the logic above to use the other commit's ref assembly instead of the ref pack's ref assembly, otherwise the process is identical.