From 4ace62b32425c25bb2148b75f0449fbca18f884e Mon Sep 17 00:00:00 2001 From: "dobby-yivi-agent[bot]" <275734547+dobby-yivi-agent[bot]@users.noreply.github.com> Date: Fri, 21 Aug 2026 13:23:21 +0000 Subject: [PATCH] docs(postguard-dotnet): document the pg-ffi pin, testing and the tracked public API surface Landed from postguard-dotnet's CLAUDE.md, which encryption4all/dobby-code#696 cuts back to orientation. This is the half of that file that was documentation rather than a durable check: how the pinned pg-ffi release is consumed, how to run the tests across both target frameworks, and how PublicApiAnalyzers gates the public surface. Refs: encryption4all/dobby-code#696 --- docs/repos/postguard-dotnet.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/repos/postguard-dotnet.md b/docs/repos/postguard-dotnet.md index 531a18f..6dc6835 100644 --- a/docs/repos/postguard-dotnet.md +++ b/docs/repos/postguard-dotnet.md @@ -93,12 +93,32 @@ cd ../postguard/pg-ffi This compiles the Rust FFI crate and copies the native library to `src/runtimes/`. +CI and the NuGet publish do not build the crate. They download pre-built binaries from the release pinned in `.github/pg-ffi-version`, a one-line file holding the exact `encryption4all/postguard` release tag both workflows pass to `gh release download`. Bump that file to move to a newer release, and check out the same tag when you want a local build of the binaries that ship. + ### Build the .NET solution ```bash dotnet build E4A.PostGuard.slnx ``` +### Testing + +```bash +dotnet test E4A.PostGuard.slnx +``` + +The solution multi-targets `net8.0` and `net10.0`, so a plain `dotnet test` needs both runtimes installed. Pass `--framework net10.0` to run against one of them. CI exercises both. + +### Public API surface + +`src/PublicAPI.Shipped.txt` and `src/PublicAPI.Unshipped.txt` list every public member of `E4A.PostGuard`. Microsoft.CodeAnalysis.PublicApiAnalyzers checks them during `dotnet build`, so changing the public surface without updating the files fails the build. There is no separate CI step. Severity is raised through `` in `src/E4A.PostGuard.csproj` rather than `.editorconfig`, because path-based `.editorconfig` severity does not reach the analyzer's additional files. + +Add a new member to `PublicAPI.Unshipped.txt`. Record a removal in the same file as `*REMOVED*` followed by the exact line from the shipped file. To get a line in the right format, build and copy the signature out of the `RS0016` message, which prints it as `Namespace.Type.Member(args) -> ret`. IDEs offer the same text as a code fix on the diagnostic. + +Both target frameworks produce the same surface today, since `src/` has no `#if`, so one pair of files covers both. A member that becomes framework-conditional would need the files split per framework. + +At release time, move the `PublicAPI.Unshipped.txt` entries into `PublicAPI.Shipped.txt`, applying `*REMOVED*` lines as deletions, and leave the unshipped file with only its `#nullable enable` header. Release-please does not do this. + ### Run the example See [postguard-examples/pg-dotnet](https://github.com/encryption4all/postguard-examples/tree/main/pg-dotnet). @@ -107,7 +127,7 @@ See [postguard-examples/pg-dotnet](https://github.com/encryption4all/postguard-e This repository uses [Release-please](https://github.com/googleapis/release-please) for automated versioning. When changes are merged to `main`, Release-please creates a release PR. Merging that PR triggers: -1. Download of `pg-ffi` native libraries from the [postguard](https://github.com/encryption4all/postguard) releases (linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64) +1. Download of `pg-ffi` native libraries from the [postguard](https://github.com/encryption4all/postguard) release pinned in `.github/pg-ffi-version` (linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64) 2. NuGet package publishing via trusted OIDC publishing ## CI/CD