docs: adds information about promoting shipped APIs

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

Author: baywet

CONTRIBUTING.md

@@ -74,4 +74,34 @@ The recommended commit types used are:
 - __ci__ for CI configuration file changes e.g. updating a pipeline
 - __chore__ for miscallaneous non-sdk changesin the repo e.g. removing an unused file
 
-Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version.
+Adding an exclamation mark after the commit type (`feat!`) or footer with the prefix __BREAKING CHANGE:__ will cause an increment of the _major_ version.
+
+## Updates to public API surface
+
+Because we need to maintain a compatible public API surface within a major version, this project is using the public API analyzers to ensure no prior public API is changed/removed inadvertently.
+
+This means that:
+
+- All entries in an __Unshipped__ document need to be moved to the __Shipped__ document before any public release.
+- All new APIs being added need to be __Unshipped__ document before the pull request can be merged, otherwise build will fail with a message like the example below.
+
+```txt
+Error: /home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Models/OpenApiSecurityScheme.cs(39,46): error RS0016: Symbol 'OAuth2MetadataUrl.set' is not part of the declared public API (https://github.com/dotnet/roslyn-analyzers/blob/main/src/PublicApiAnalyzers/PublicApiAnalyzers.Help.md) [/home/runner/work/OpenAPI.NET/OpenAPI.NET/src/Microsoft.OpenApi/Microsoft.OpenApi.csproj::TargetFramework=net8.0]
+```
+
+### Update the unshipped document
+
+To update the unshipped document, simply run the following commands
+
+```shell
+# add the missing public api entries
+dotnet format --diagnostics RS0016
+# discard changes to cs files to avoid creating conflicts
+git checkout *.cs
+```
+
+### Move items from unshipped to unshipped document
+
+```pwsh
+. ./scripts/promoteUnshipped.ps1
+```

scripts/promoteUnshipped.ps1

@@ -0,0 +1,13 @@
+$nullableConstant = "#nullable enable"
+$unshippedDocuments = ls *.Unshipped* -R | Select-Object -ExpandProperty FullName
+foreach ($unshippedDocumentPath in $unshippedDocuments) {
+    $shippedDocumentPath = $unshippedDocumentPath -replace '\.Unshipped', '.Shipped'
+    $unshippedDocumentContent = Get-Content $unshippedDocumentPath -Raw
+    $unshippedDocumentContent = ($unshippedDocumentContent -replace [regex]::Escape($nullableConstant), '').Trim()
+    if ([string]::IsNullOrWhiteSpace($unshippedDocumentContent)) {
+        Write-Host "No content to promote for $unshippedDocumentPath, skipping." -ForegroundColor Yellow
+        continue
+    }
+    Add-Content -Path $shippedDocumentPath -Value $unshippedDocumentContent -Verbose
+    Set-Content -Path $unshippedDocumentPath -Value $nullableConstant -Verbose
+}