Public API diffs (SteeltoeOSS#1564)

* Add PublicAPI scripts

* TEST: .\public-api-mark-shipped.ps1

* TEST: Steeltoe changes after release

* TEST: .\public-api-mark-shipped.ps1

* Revert test commits

Author: bart-vmware

.github/workflows/package.yml

@@ -102,6 +102,17 @@ jobs:
         echo "Package version suffix is empty. This should never happen."
         exit 1
 
+    - name: Verify public API files (for release)
+      if: ${{ github.event_name == 'release' }}
+      shell: pwsh
+      run: |
+        # To recover from this:
+        # - Delete the GitHub release
+        # - Run: git push --delete origin the-invalid-tag-name
+        # - Run public-api-mark-shipped.ps1, commit and push
+        # - Recreate the GitHub release
+        ./public-api-verify-shipped.ps1
+
     - name: Build solution
       run: dotnet build ${{ env.SOLUTION_FILE }} --no-restore --configuration Release --verbosity minimal /p:VersionSuffix=${{ env.PACKAGE_VERSION_SUFFIX }}
 

public-api-mark-shipped.ps1

@@ -0,0 +1,46 @@
+# This script merges the content of PublicAPI.Unshipped.txt files into PublicAPI.Shipped.txt.
+# Run this before creating a new release and commit the changes.
+# Based on https://github.com/dotnet/roslyn/blob/main/scripts/PublicApi/mark-shipped.ps1
+#
+# TIP: To obtain the public API diff between two releases, run:
+# git diff --unified=0 --text <previous-release-tag-name> head -- **/PublicAPI.Shipped.txt
+
+[CmdletBinding(PositionalBinding=$false)]
+param ()
+
+Set-StrictMode -version 2.0
+$ErrorActionPreference = 'Stop'
+
+function MarkShipped([string] $dir) {
+    $shippedFilePath = Join-Path $dir 'PublicAPI.Shipped.txt'
+    $shipped = Get-Content $shippedFilePath
+    if ($null -eq $shipped) {
+        $shipped = @('#nullable enable')
+    }
+
+    $unshippedFilePath = Join-Path $dir 'PublicAPI.Unshipped.txt'
+    $unshipped = Get-Content $unshippedFilePath
+    $removed = @()
+    $removedPrefix = '*REMOVED*';
+    Write-Host "Processing $dir"
+
+    foreach ($item in $unshipped) {
+        if ($item.Length -gt 0) {
+            if ($item.StartsWith($removedPrefix)) {
+                $item = $item.Substring($removedPrefix.Length)
+                $removed += $item
+            }
+            elseif (-not $item.StartsWith('#')) {
+                $shipped += $item
+            }
+        }
+    }
+
+    $shipped | Sort-Object -Unique | Where-Object { -not $removed.Contains($_) } | Out-File $shippedFilePath -Encoding Ascii
+    '#nullable enable' | Out-File $unshippedFilePath -Encoding Ascii
+}
+
+foreach ($file in Get-ChildItem -re -in 'PublicApi.Shipped.txt') {
+    $dir = Split-Path -parent $file
+    MarkShipped $dir
+}

public-api-verify-shipped.ps1

@@ -0,0 +1,30 @@
+# This script verifies that all PublicAPI.Unshipped.txt files are empty.
+# Run this as a sanity check before creating a new release.
+
+[CmdletBinding(PositionalBinding=$false)]
+param ()
+
+Set-StrictMode -version 2.0
+$ErrorActionPreference = 'Stop'
+
+function HasUnshipped([string] $dir) {
+    $filePath = Join-Path $dir 'PublicAPI.Unshipped.txt'
+    $content = Get-Content $filePath | Where-Object { $_ -NOTLIKE "#*" }
+    return [bool]$content
+}
+
+$dirsUnshipped = @()
+
+foreach ($file in Get-ChildItem -re -in 'PublicApi.Unshipped.txt') {
+    $dir = Split-Path -parent $file
+    $hasUnshipped = HasUnshipped $dir
+
+    if ($hasUnshipped) {
+        $dirsUnshipped += $dir
+    }
+}
+
+if ($dirsUnshipped.Count -gt 0) {
+    Write-Error "Unshipped APIs found in the following directories:`n$($dirsUnshipped -join "`n")"
+    return 1
+}