Skip to content

Latest commit

 

History

History
636 lines (527 loc) · 43.4 KB

RELEASING.md

File metadata and controls

636 lines (527 loc) · 43.4 KB

Releasing AgentExperience.NET

This is the release procedure and the release verification checks, in the order they run. Every check is a command you can paste into an interactive bash or zsh shell; each prints an explicit OK or FAILED line rather than leaving a judgement to whoever is running it, and each multi-line check runs in a ( ... ) subshell so a failure never closes your terminal. Automation builds, tests, packs, and verifies on every pull request, every push to main, and a weekly schedule (.github/workflows/ci.yml). Publishing takes two maintainer actions: pushing a version tag, and approving the deployment it starts (step 10). Only .github/workflows/release.yml can publish. It re-runs these checks on the tagged commit, pushes to nuget.org with a short-lived key from NuGet Trusted Publishing, tags the Go modules, and uploads the Python distribution to PyPI through PyPI Trusted Publishing, so no API key or token is stored in the repository or its secrets. A release test holds that workflow to its constraints, and fails if any other workflow gains a publish step, a PyPI upload, a tag push, a key, or a write permission.

What a release is today

A release ships eight packages: AgentExperience.Abstractions, AgentExperience.Core, AgentExperience.MicrosoftAgentFramework, AgentExperience.Storage.Postgres, AgentExperience.Storage.Postgres.Vectors, AgentExperience.Storage.InMemory (development and tests only), AgentExperience.Storage.Sqlite (one local file) and AgentExperience.Cli (the aexp .NET tool: a CLI and an MCP server; a tool package, which carries its own dependencies and has no public API). The last two are new in the release after 0.1.0-preview.17. Every count below — eight packages, eight symbol packages, eight API baselines — is that list; eng/verify-packages.cs and release.yml hold it too. The first release that carries a package ID nuget.org has never seen needs one extra check, described under First publish of a new package ID.

The GitHub release also carries five self-contained aexp binaries and their SHA256SUMS as assets (story 29.3): aexp-linux-x64, aexp-linux-arm64, aexp-osx-arm64, aexp-osx-x64 and aexp-win-x64.exe, built by eng/publish-binaries.sh on the tagged commit (step 7a), their sums quoted in the release notes, so scripts/install-aexp.sh can install aexp on a machine with no .NET at all.

The same tag also releases the two ports, at the same version, from the same verified commit:

  • Python: the distribution agenticexperience (python/), an sdist and a wheel, on PyPI. The first release that carries it is described under First publish to PyPI.
  • Go: the six modules under go/: github.com/fabbrik/AgentExperience.NET/go, .../go/inmemory, .../go/postgres, .../go/postgres/pgtest, .../go/maf and .../go/telemetry (the optional OpenTelemetry adapter; nothing else requires it). A Go module is released by a tag named after its directory, go/vX, go/inmemory/vX, and so on, which the Go module proxy serves from then on.

Every release from this repository is a preview — 0.1.0-preview.N, set once in Directory.Build.props — and claims no production readiness. That is not modesty; it is the acceptance criterion's own condition: support limits are documented before claiming production readiness, and any unresolved item blocks that claim. An unresolved item is a row in the Known limits table, or an open item on the maintainers' deferred-work ledger. The Documented boundaries are documented support limits that no code change can remove, so they do not block the claim (see the decision below). Step 9 checks that the version says preview while any known limit remains, and states what dropping the suffix requires.

This version still claims no production readiness. Even with the Known limits table empty and the deferred-work ledger closed, dropping the suffix is a maintainer's decision, not something step 9 makes.

The version is deliberately not 1.0.0. With no version property at all, dotnet pack would emit 1.0.0 — a stability promise this codebase declines to make while it still ships documented breaking changes between previews.

The version is set once, in Directory.Build.props, and the ports carry the version derived from it, never one of their own:

Directory.Build.props .NET packages and the tag Python (python/pyproject.toml) Go (each module's requirement on its siblings)
0.1.0 + preview.N 0.1.0-preview.N, tag v0.1.0-preview.N 0.1.0aN v0.1.0-preview.N
1.0.0, no suffix 1.0.0, tag v1.0.0 1.0.0 v1.0.0

Python's is an explicit PEP 440 alpha: PEP 440 would read 0.1.0-preview.N as a release candidate. The Go modules keep their replace directives, so builds in this repository and CI use the tree; a consumer ignores them and resolves the siblings at the same tag. A release test, and the tagged run's verify job, fail when any of these disagrees with Directory.Build.props.

To cut the next preview, bump the suffix (for example preview.2 → preview.3) in Directory.Build.props, set the same version in python/pyproject.toml (and python/uv.lock, with uv lock in python/) and in every go/*/go.mod requirement on another module of this repository, add that version's section to CHANGELOG.md (step 10's release notes are built from it), and nothing else. The release test names every file that disagrees, and the version it expects there:

dotnet test tests/AgentExperience.Release.Tests --filter "FullyQualifiedName~VersionAgreementTests"

Once it is published, move the package-validation baseline to it (after the release).

Decision: known limits and documented boundaries

Status: accepted, after 0.1.0-preview.2; reversible. Made on the owner's behalf under a standing instruction to proceed without waiting.

Context. The original release criteria froze the gate as "the Known limits table is empty and the deferred-work ledger is closed", with "a row leaves the table only by fixing the limit". By 0.1.0-preview.2, thirteen of the sixteen limits were resolved and three (KL-2, KL-11, KL-12) were narrowed as far as they go. What is left of each is inherent: erasure cannot reach derived search data PostgreSQL has to read in the clear, or copies the library never sees; no check can tell that a model used a lesson it was given, or see past the host's own bookkeeping and key custody; and no provider can make a model unread an earlier block in a history the host owns. No code change can fix a limit that cannot be fixed, so under the frozen gate 1.0 was unreachable.

Decision. The table is split in two, and both halves now live in docs/known-limits.md (they were in the root README when this was decided). Known limits are unresolved problems a code change could fix; they block 1.0, and a row still leaves only by fixing it. Documented boundaries are properties the library cannot remove by code; each states the boundary exactly, why no code change can remove it, and what the library does about it, and they do not block 1.0. KL-2, KL-11 and KL-12 move to the boundaries with their numbers and wording unchanged. A row may move from limits to boundaries only with a written reason why no code change can remove it, and it returns to the limits table if that reason stops holding. Step 9, and the same step in release.yml, count only the Known limits table's rows.

Consequences. The gate is reachable: dropping the preview suffix requires an empty Known limits table and a closed deferred-work ledger. The boundaries become support limits a 1.0 ships with, stated, rather than defects it must not ship with. The risk is that "inherent" becomes a way to stop fixing things; the written reason, which a reviewer can challenge, and the rule that a boundary returns when its reason fails are the guard. Reversing the decision means moving the three rows back and restoring the old count; nothing else depends on it.

Prerequisites

  • The commit you are releasing, checked out, with a clean tree.
  • Docker running: the storage tests start PostgreSQL containers (16 by default; step 3 runs every supported major). If Testcontainers' Ryuk container fails under your Docker setup (Rancher Desktop, for example), export TESTCONTAINERS_RYUK_DISABLED=true first.
  • Network access to nuget.org (restore, the upgrade suite's seeders, which restore the published previews, and the probes in step 6).
( test -z "$(git status --porcelain)" && echo "Clean tree OK" || echo "FAILED: the working tree is not clean" )

The checks

1. The exact pinned SDK

global.json rolls forward for day-to-day development; a release does not.

( pinned="$(sed -nE 's/.*"version": *"([^"]+)".*/\1/p' global.json)"; actual="$(dotnet --version)"
  if [ "$actual" = "$pinned" ]; then echo "SDK OK: $actual"; else echo "FAILED: SDK $actual is in use, global.json pins $pinned"; false; fi )

2. Locked restore and a deterministic release build

--locked-mode fails if any packages.lock.json disagrees with what its project asks for, so the build uses exactly the dependency graph that was reviewed. AgentExperienceReleaseBuild turns on ContinuousIntegrationBuild for the shipping projects only, which maps their source paths to /_/ so the packages do not depend on where the repository was cloned. Never pass -p:ContinuousIntegrationBuild=true itself: as a global property it would reach the test projects too, and the tests that locate checked-in files through [CallerFilePath] would then look under /_/.

dotnet restore --locked-mode
for seeder in tests/AgentExperience.Upgrade.Seeders/Preview*/; do dotnet restore "$seeder" --locked-mode; done
dotnet build --no-restore --configuration Release -p:AgentExperienceReleaseBuild=true

The second line restores the upgrade suite's seeders, which are not in the solution: each pins a published preview's packages, and step 3's upgrade tests build and run them.

3. The full test suite

Core, PostgreSQL, the MAF adapter, the end-to-end sample, the reuse baseline, the compatibility proofs, the upgrades from databases the published previews created, and the release gates, on net10.0 (the one target framework), against PostgreSQL 16. This is also the security suite: every test in docs/security-suite.md runs here, and there is no separate, weaker security build.

dotnet test --no-build --configuration Release

Then the container-backed suites once per supported PostgreSQL major. The list is read from CI's postgres matrix, which a release test holds equal to the list the fixtures accept, so this runs exactly what CI runs:

( ok=true
  majors="$(sed -nE 's/^ *postgres: \[([0-9, ]+)\].*/\1/p' .github/workflows/ci.yml | tr -d ' ' | tr ',' ' ')"
  [ -n "$majors" ] || { echo "FAILED: no postgres matrix in .github/workflows/ci.yml"; ok=false; }
  for major in $(echo "$majors"); do   # $(...) splits the list in zsh as well as bash
    for project in tests/AgentExperience.Storage.Postgres.Tests tests/AgentExperience.Storage.Postgres.Vectors.Tests \
                   tests/AgentExperience.CompatibilityProof tests/AgentExperience.Sample.EndToEnd.Tests \
                   tests/AgentExperience.Upgrade.Tests tests/AgentExperience.Contract.Tests; do
      AGENTEXPERIENCE_POSTGRES_MAJOR="$major" dotnet test "$project" --no-build --configuration Release \
        || { echo "FAILED: $project on PostgreSQL $major"; ok=false; }
    done
    # The store and vector suites again, unmodified, in crypto-shredding mode.
    for project in tests/AgentExperience.Storage.Postgres.Tests tests/AgentExperience.Storage.Postgres.Vectors.Tests; do
      AGENTEXPERIENCE_TEST_ENCRYPTION=on AGENTEXPERIENCE_POSTGRES_MAJOR="$major" dotnet test "$project" --no-build --configuration Release \
        || { echo "FAILED: $project on PostgreSQL $major, crypto-shredding mode"; ok=false; }
    done
    # And with row-level security on: the store, vector, sample and upgrade suites behind the policies (story 15.1).
    for project in tests/AgentExperience.Storage.Postgres.Tests tests/AgentExperience.Storage.Postgres.Vectors.Tests \
                   tests/AgentExperience.Sample.EndToEnd.Tests tests/AgentExperience.Upgrade.Tests; do
      AGENTEXPERIENCE_TEST_RLS=on AGENTEXPERIENCE_POSTGRES_MAJOR="$major" dotnet test "$project" --no-build --configuration Release \
        || { echo "FAILED: $project on PostgreSQL $major, row-level security mode"; ok=false; }
    done
    # And with both: row-level security and crypto-shredding together.
    for project in tests/AgentExperience.Storage.Postgres.Tests tests/AgentExperience.Storage.Postgres.Vectors.Tests; do
      AGENTEXPERIENCE_TEST_RLS=on AGENTEXPERIENCE_TEST_ENCRYPTION=on AGENTEXPERIENCE_POSTGRES_MAJOR="$major" \
        dotnet test "$project" --no-build --configuration Release \
        || { echo "FAILED: $project on PostgreSQL $major, row-level security and crypto-shredding mode"; ok=false; }
    done
  done
  $ok && echo "PostgreSQL matrix OK: $majors" )

4. The named gates, one by one

All of these already ran in step 3. Run them again by name so the release log shows each gate passing on its own line — and so a gate that was accidentally filtered out of step 3 cannot hide.

# Deletion and retention, against a real PostgreSQL (16 unless AGENTEXPERIENCE_POSTGRES_MAJOR says otherwise).
dotnet test tests/AgentExperience.Storage.Postgres.Tests --no-build --configuration Release --filter "FullyQualifiedName~PostgresDeletionTests"

# The two-role deployment. The application role owns nothing, cannot rewrite, remove or truncate a
# ledger whatever marker it sets, and reaches a purge only when the host opts in. (Every other store test in that
# project also runs as the application role.)
dotnet test tests/AgentExperience.Storage.Postgres.Tests --no-build --configuration Release --filter "FullyQualifiedName~PostgresApplicationRoleTests"

# The schema migrator reaches no console, Trace, ILogger or activity sink, on a clean run or a failing script.
dotnet test tests/AgentExperience.Storage.Postgres.Tests --no-build --configuration Release --filter "FullyQualifiedName~MigratorLogSilenceTests"

# Release gates: the public API baseline of all eight assemblies, the compatibility proof's agreement with the
# shipping pins, the security-suite map, and the workflow guard (only release.yml publishes, as step 10 describes).
dotnet test tests/AgentExperience.Release.Tests --no-build --configuration Release

# A failing baseline leaves *.received.txt behind (gitignored, so look for it directly); there must be none,
# and all eight baselines must be there.
( dir=tests/AgentExperience.Release.Tests/PublicApi
  if [ ! -d "$dir" ]; then echo "FAILED: $dir is missing"; false
  elif [ "$(find "$dir" -name '*.verified.txt' | wc -l)" -ne 8 ]; then echo "FAILED: $dir does not hold eight baselines"; false
  elif [ -n "$(find "$dir" -name '*.received.*')" ]; then echo "FAILED: a public API baseline does not match: $(find "$dir" -name '*.received.*')"; false
  else echo "API baseline OK"; fi )

A public API change is never accepted here. If the baseline fails, the change goes back through review: AGENTEXPERIENCE_ACCEPT_API_CHANGES=true dotnet test tests/AgentExperience.Release.Tests --filter "FullyQualifiedName~PublicApi" regenerates it, and the resulting git diff is what gets reviewed and committed.

5. Every pin has source-backed evidence

docs/compatibility-evidence.md carries one row per SDK, MAF, storage, and telemetry pin — MAF's range and every floor: where it is declared, its nuget.org source, the content hash NuGet restored, and the test that proves it. These two loops check that the document and the committed lock files describe the same packages, byte for byte.

(
  ok=true
  # The document must cite hashes at all, or the first loop passes vacuously.
  [ "$(grep -cE '`[A-Za-z0-9+/]{86}==`' docs/compatibility-evidence.md)" -gt 0 ] \
    || { echo "FAILED: docs/compatibility-evidence.md cites no content hashes"; ok=false; }
  # Every hash the evidence cites is one a lock file actually restored...
  for h in $(grep -oE '`[A-Za-z0-9+/]{86}==`' docs/compatibility-evidence.md | tr -d '`'); do
    grep -qF "$h" src/*/packages.lock.json || { echo "FAILED: the evidence cites a hash no lock file has: $h"; ok=false; }
  done
  # ...and every package a shipping project pins directly has an evidence row.
  for h in $(grep -h -A4 '"type": "Direct"' src/*/packages.lock.json | sed -nE 's/.*"contentHash": "([^"]+)".*/\1/p' | sort -u); do
    grep -qF "$h" docs/compatibility-evidence.md || { echo "FAILED: a direct pin has no evidence row: $h"; ok=false; }
  done
  $ok && echo "Pin evidence OK"
)

Then read the document's Last verified date. If any pin or floor moved since, re-verify the moved rows against nuget.org and update the date before continuing.

6. The MAF compatibility matrix, and the floating dependencies

Microsoft.Agents.AI is a range, [floor, next major), so both ends are support claims and both probes are release blockers: the floor, and the newest stable version inside the range. Both run on a throwaway copy of the tracked files (HEAD plus uncommitted changes to them); untracked files are not copied, and the script warns when src/ or tests/ has any. The floor restores the committed lock files exactly (--locked-mode); a newer version has to re-evaluate them.

eng/probe-maf-version.sh pinned   # the range's floor: must print "... PASSED" and exit 0
eng/probe-maf-version.sh          # newest stable inside the range: must print "... PASSED" and exit 0; record it in docs/compatibility-evidence.md

If the newest stable MAF on nuget.org is outside the range (a new major), the second command says so and probes the newest version inside it. Probing the new major itself (eng/probe-maf-version.sh <version>) is information for the evidence document, not a release blocker; widening the range is a deliberate change.

Every other dependency is a floor, which claims every later release in its major, so the newest ones must pass too. This one is a release blocker as well. Like the MAF probe it works on a throwaway copy of the tracked files:

eng/probe-floating-dependencies.sh   # must print "... PASSED" and exit 0; record the resolved table in the evidence

7. Pack, and verify the packages themselves

Packing also runs the SDK's package validation: each package is compared with the same package at the last published preview (AgentExperiencePackageValidationBaseline in Directory.Build.props, which step 2's restore downloads into the NuGet cache), and any binary break that no src/<Project>/CompatibilitySuppressions.xml declares fails the pack. A release test (step 3) checks that a declared break has a CHANGELOG bullet or heading starting with Breaking, and that the baseline is the last release in the CHANGELOG.

Assertions are made against the built .nupkg and .snupkg files, not the csproj files: sixteen artifacts (eight packages, eight symbol packages) at 0.1.0-preview.N; license, readme, tags, and repository metadata with the SourceLink commit; "Preview" in the description, release notes, and readme; exactly the net10.0 build under lib/, and the exact dependency set — ids and version ranges — in its dependency group, so Abstractions, Core and the in-memory store carry no MAF, Npgsql, DbUp, Pgvector, model-provider or OpenTelemetry dependency (and the in-memory store no Core); one repository commit across all eight packages, equal to git rev-parse HEAD; and, per framework, in each symbol package, a PDB whose id matches its assembly's CodeView debug entry, whose every SourceLink target points at this repository, whose every path is mapped to /_/, and whose assembly is marked reproducible.

rm -rf artifacts/packages
dotnet pack --no-build --configuration Release --output artifacts/packages -p:AgentExperienceReleaseBuild=true
dotnet run eng/verify-packages.cs -- artifacts/packages

7a. The self-contained binaries

The five aexp binaries the release attaches (story 29.3), built by the script release.yml and ci.yml both run: a locked restore against the binaries' own lock file (src/AgentExperience.Cli/packages.binaries.lock.json), then one self-contained, single-file publish per runtime, renamed aexp-<rid> (.exe for Windows), and their SHA256SUMS. The check asserts exactly six files, the sums, that the tool package was left alone (no lock file changed; step 7's packages are unaffected), and that this machine's binary prints the version, run through the install script as a stranger would run it, with the full adoption path behind it (eng/prove-adoption-path.sh --binaries: the tampered copy refused, then init, trust, a failed and a verified run, recall, lessons, benefit; no dotnet call at all).

( version="$(scripts/release-version.sh dotnet)"
  rm -rf artifacts/binaries
  eng/publish-binaries.sh artifacts/binaries \
    && [ "$(find artifacts/binaries -type f | wc -l)" -eq 6 ] \
    && (cd artifacts/binaries && (sha256sum --check --strict SHA256SUMS 2>/dev/null || shasum -a 256 -c SHA256SUMS)) \
    && [ -z "$(git status --porcelain -- '*packages.lock.json')" ] \
    && eng/prove-adoption-path.sh --binaries artifacts/binaries \
    && echo "Binaries OK: aexp $version" || echo "FAILED: see above" )

release.yml's verify job runs the build and the file, sum and version checks on its Linux runner; the other four binaries are proven on their own hardware by CI's adoption-path-binary legs on main.

8. The sample, twice, byte for byte

The sample's promise is one command, no Docker, no database, no credentials, and the same transcript every time.

( out="$(mktemp -d)"
  dotnet run --project samples/AgentExperience.Sample.EndToEnd --configuration Release --no-build > "$out/run-1.txt" \
    && dotnet run --project samples/AgentExperience.Sample.EndToEnd --configuration Release --no-build > "$out/run-2.txt" \
    && diff -u "$out/run-1.txt" "$out/run-2.txt" \
    && diff -u tests/AgentExperience.Sample.EndToEnd.Tests/GoldenTranscript.txt "$out/run-1.txt" \
    && echo "Sample OK" || echo "FAILED: the sample did not run, or its transcript differs (diff above)"
  rm -rf "$out" )

9. The production-readiness gate

A release may drop the preview suffix only when the Known limits table in docs/known-limits.md is empty and every item on the maintainers' deferred-work ledger (deferred-work.md in their implementation artifacts, kept out of the repository) is closed. A row leaves the Known limits table only by fixing the limit it describes, or by moving to Documented boundaries with a written reason why no code change can remove it. Documented boundaries do not block. While any known limit remains, the version must say preview. The check counts only the rows of the ## Known limits section, so a boundary's KL- row is not counted:

( if ! grep -qx '## Known limits' docs/known-limits.md; then
    echo "FAILED: docs/known-limits.md has no '## Known limits' section to count"; false
  else
    limits="$(awk '/^## / { section = ($0 == "## Known limits") } section' docs/known-limits.md | grep -cE '^\| KL-[0-9]+ \|' || true)"
    if grep -qE '<VersionSuffix>preview\.[1-9][0-9]*</VersionSuffix>' Directory.Build.props; then
      if [ "$limits" -gt 0 ]; then
        echo "$limits known limit(s): this is a preview release, and it is versioned as one."
      else
        echo "No known limits: this is a preview release, and it is versioned as one. Dropping the preview suffix requires this empty Known limits table and a closed deferred-work ledger."
      fi
    elif [ "$limits" -gt 0 ]; then
      echo "FAILED (BLOCKED): $limits known limit(s), but Directory.Build.props does not version this as a preview."; false
    else
      echo "No known limits and no preview suffix: confirm the deferred-work ledger is closed before releasing."
    fi
  fi )

Today it prints No known limits: this is a preview release, and it is versioned as one. followed by what dropping the suffix requires. The ledger is not in the repository, so no command can check it; the maintainer who drops the suffix confirms it is closed.

Before moving on, record the commit steps 1–9 verified; step 10 refuses to tag anything else:

verified="$(git rev-parse HEAD)"; echo "Verified commit: $verified"

10. Tag and approve (maintainer only)

Only after steps 1–9 have passed on the exact commit being released, in the same shell that recorded $verified, and only once that commit is on main. Tag it and push the tag:

( version="$(scripts/release-version.sh dotnet)"
  git fetch origin main
  if [ -z "${verified:-}" ] || [ "$(git rev-parse HEAD)" != "$verified" ]; then
    echo "FAILED: HEAD is not the commit steps 1-9 verified ($verified); re-run the checks"; false
  elif ! git merge-base --is-ancestor "$verified" origin/main; then
    echo "FAILED: $verified is not on origin/main; merge it first"; false
  else
    git tag -a "v$version" -m "AgentExperience.NET $version (preview)" "$verified" \
      && git push origin "v$version" \
      && echo "Tagged v$version: now approve the nuget-release deployment, then pypi-release" || { echo "FAILED: see above"; false; }
  fi )

The tag starts .github/workflows/release.yml. Its verify job first refuses a tag that is not v plus the version in Directory.Build.props, and a commit that is not reachable from main. It then re-runs, on the tagged commit, the pinned SDK (step 1), the locked restore and release build (step 2), the full test suite against the default PostgreSQL major (the first command of step 3; the per-major and crypto-shredding runs, and steps 4–6 and 8, are not repeated there: they are what you ran locally, and CI's postgres, maf-compatibility and floating-dependencies jobs on main), pack and package verification (step 7), and the production-readiness gate (step 9). It also checks that python/pyproject.toml and every Go module's requirement on its siblings carry the version derived from Directory.Build.props (see What a release is today); builds the Python sdist and wheel with a pinned uv, checks that they are agenticexperience at that version (twine check --strict and the wheel's metadata), and runs the Python tests; and runs go vet and go test in each Go module (the PostgreSQL legs of both ports are not repeated: CI on main ran them). It builds the five self-contained binaries (step 7a) and checks them: six files, sha256sum --check --strict SHA256SUMS, and aexp-linux-x64 --version printing the tagged version. It builds the release notes from this version's CHANGELOG.md section, and fails if there is none, then appends a ## Binaries section (the install one-liner and the SHA256SUMS lines). Last, it uploads what it verified: the NuGet packages, the release notes, the binaries, and the Python distribution as its own artifact. It publishes nothing.

Then approve the deployments, two of them. Open the run under the repository's Actions tab, choose Review deployments, select nuget-release, and approve. The publish job then:

  1. downloads exactly the files verify uploaded (it does not check out or build anything);
  2. exchanges the job's GitHub OIDC token for a short-lived nuget.org key through NuGet/login;
  3. runs dotnet nuget push "artifacts/packages/*.nupkg" --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate, with the short-lived key from step 2, which uploads each .snupkg alongside its .nupkg;
  4. tags the six Go modules at the tagged commit, through the GitHub API with the job's own token: go/vX, go/inmemory/vX, go/postgres/vX, go/postgres/pgtest/vX, go/maf/vX and go/telemetry/vX, where vX is the tag. A tag that already points at that commit is kept; one that points anywhere else fails the job here, before the GitHub release. It then asks proxy.golang.org for each module at that version, and fails if the proxy does not know one after ten attempts, 30 seconds apart (at worst about 57 minutes for all six; the job's timeout is 75 minutes);
  5. only then creates the GitHub release for the tag: a prerelease when the version has a suffix, with that version's CHANGELOG.md section, the Known limits table (or "None currently.") and the Documented boundaries table from docs/known-limits.md as its notes, and the five binaries and SHA256SUMS (downloaded from verify and their sums checked again just before, as the Python distribution's are) attached as its assets. A preview's release notes say what it does not promise. On a re-run, an existing release keeps its notes and gets its assets completed (gh release upload --clobber) instead of being left as it is.

When publish has succeeded, the run asks for the second approval: select pypi-release and approve. The publish-pypi job downloads exactly the sdist and wheel verify uploaded (it checks nothing out and builds nothing), checks they are the tagged version, and uploads them to PyPI with pypa/gh-action-pypi-publish through PyPI Trusted Publishing: the job's OIDC token is exchanged for a short-lived PyPI token, and no token is stored anywhere. skip-existing makes a re-run skip the files PyPI already has.

If publish fails part-way, re-run the failed job from the Actions tab (it needs approving again): --skip-duplicate skips the packages nuget.org already has, Go tags already at the commit are kept, and an existing GitHub release keeps its notes and gets the binaries uploaded again (replacing assets of the same name). If publish fails at the Go module proxy check, nuget.org and the Go tags stand, but the GitHub release and PyPI wait: publish-pypi runs only after publish succeeds. Re-run publish (the tags are kept, and the proxy check runs again); the proxy can remember that a version was not found for up to about 30 minutes, so wait that long before re-running if the tags were only just created. If publish-pypi fails, nuget.org, the Go tags and the GitHub release stand; fix the cause and re-run that job alone.

A publish job can be re-run only while the artifacts verify uploaded are retained: 30 days for the NuGet packages, the release notes and the binaries, 90 days (the most GitHub allows) for the Python distribution. After that, delete the version tag and push it again at the same commit (step 10's commands), which runs verify again and rebuilds them; everything already published is skipped. If verify fails, nothing was published: fix the cause on main, delete the tag (git push origin :refs/tags/vX and git tag -d vX), and tag again. A version pushed by mistake cannot be deleted from nuget.org — unlist it (and, if it is harmful, mark it deprecated) on its nuget.org page, then publish the next preview. The same holds for PyPI (yank the release) and for the Go module proxy, which serves a tagged version for ever (add a retract directive to the module's go.mod in the next release).

One-time setup

All four must exist before the first tagged release that publishes to them. Without a policy or publisher, a publish job cannot log in; without an environment's reviewers, its job would run without an approval.

  • The nuget.org Trusted Publishing policy. Signed in to nuget.org as fabbrik76, open Trusted Publishing from the account menu and add a GitHub Actions policy: owner fabbrik, repository AgentExperience.NET, workflow file release.yml, environment nuget-release. The policy lets the workflow's OIDC token be exchanged for a key only from that file, in that environment, in this repository, for packages fabbrik76 owns.
  • The GitHub environment nuget-release. In the repository's Settings → Environments, create nuget-release and add the maintainers as required reviewers. Under Deployment branches and tags, choose Selected branches and tags and add the tag rule v*, so no other ref can reach the environment. Add no environment secrets: the workflow needs none.
  • The PyPI pending Trusted Publisher. Signed in to pypi.org as the maintainer, open Your account → Publishing and add a pending GitHub publisher: PyPI project name agenticexperience, owner fabbrik, repository AgentExperience.NET, workflow name release.yml, environment name pypi-release. A pending publisher lets the workflow create the project on its first upload; from then on it is an ordinary trusted publisher of that project, and only that file, in that environment, in this repository, can publish it.
  • The GitHub environment pypi-release. As for nuget-release: create it under Settings → Environments, add the maintainers as required reviewers, restrict Deployment branches and tags to the tag rule v*, and add no secrets.

The Go modules need no setup: the job's token creates their tags, and the Go module proxy fetches a public module the first time anyone asks for it.

First publish to PyPI

The first release that carries the Python distribution creates the agenticexperience project on PyPI, through the pending publisher above.

  1. Before tagging, confirm on pypi.org that the pending publisher exists with exactly the values above, and that the pypi-release environment exists with its reviewers and tag rule.
  2. Tag and approve as usual (step 10). Watch the publish-pypi job: it must upload the sdist and the wheel.
  3. If the pending publisher is missing or wrong, publish-pypi fails alone, at the token exchange (an invalid-publisher error). nuget.org, the Go tags and the GitHub release already stand, and nothing reached PyPI. Add or correct the publisher on pypi.org, then re-run the failed publish-pypi job from the Actions tab (it needs approving again).
  4. Afterwards, https://pypi.org/project/agenticexperience/ lists the version, and the project's Publishing page shows the publisher as active rather than pending.

First publish of a new package ID

A Trusted Publishing policy lets the workflow push packages the policy's owner (fabbrik76) owns, and a package ID that has never been pushed is owned by nobody yet. Whether nuget.org lets a Trusted Publishing key create a new ID depends on the account's policy, so a release that carries a new ID is checked, not assumed. The first release with AgentExperience.Storage.InMemory (story 11.2) was one; the first release with AgentExperience.Storage.Sqlite and AgentExperience.Cli is the next, with two new IDs.

A new package also has no published version for package validation to compare with, and restore would fail trying to download one. Until its first release, its csproj sets <DisablePackageBaselineValidation>true</DisablePackageBaselineValidation> (the only package-validation property a project may set; a release test holds the rest to Directory.Build.props), and the post-release step below removes it.

  1. Before tagging, sign in to nuget.org as fabbrik76, open the Trusted Publishing policy described above, and confirm it covers new package IDs as well as the existing six. If the policy page names the packages it applies to, add AgentExperience.Storage.Sqlite and AgentExperience.Cli.

  2. Tag and approve as usual (step 10). Watch the publish job's push output: every package, the new one included, must say it was pushed or skipped as a duplicate.

  3. If nuget.org refuses the new ID (a 403 on that package alone, while the others are pushed), the tag and the other packages stand. Publish each new package once by hand, with a nuget.org API key scoped to AgentExperience.Storage.Sqlite and AgentExperience.Cli that fabbrik76 creates for this one push, from the packages the verify job uploaded (download the packages artifact from the run):

    dotnet nuget push "AgentExperience.Storage.Sqlite.*.nupkg" --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate
    dotnet nuget push "AgentExperience.Cli.*.nupkg" --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate

    Revoke that key on nuget.org straight after. From then on fabbrik76 owns the ID, the Trusted Publishing policy covers it, and every later release publishes it through OIDC like the others; re-running the failed publish job now skips it as a duplicate and creates the GitHub release.

Nothing in the repository publishes anything outside release.yml; this is the only other push, and it is a maintainer's, once per new ID.

Fallback: publishing by hand

If the workflow cannot publish (GitHub Actions or the Trusted Publishing exchange unavailable), a maintainer with a nuget.org API key scoped to these eight packages can publish from the verified working copy instead, in the same shell that recorded $verified. Packages go first and the tag second, so a failed push never leaves a tag pointing at a release that does not exist; --skip-duplicate makes a retried push safe after a partial failure. The tag push still starts release.yml: approving its publish job then skips every package already pushed and creates the GitHub release; rejecting it leaves the release to be created by hand, with the Known limits and Documented boundaries tables pasted into its notes.

( if [ -z "${verified:-}" ] || [ "$(git rev-parse HEAD)" != "$verified" ]; then
    echo "FAILED: HEAD is not the commit steps 1-9 verified ($verified); re-run the checks"; false
  else
    version="$(scripts/release-version.sh dotnet)"
    dotnet nuget push "artifacts/packages/*.nupkg" --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate \
      && git tag -a "v$version" -m "AgentExperience.NET $version (preview)" "$verified" \
      && git push origin "v$version" \
      && echo "Published and tagged $version" || { echo "FAILED: see above; packages already pushed stay pushed, and a re-run skips them"; false; }
  fi )

That key lives with the maintainer, never in this repository or its secrets. Revoke it on nuget.org once it has been used.

The ports, by hand, from the same verified working copy and only once the version tag exists (so they ship the commit the tag names). The Python distribution needs a PyPI API token scoped to the agenticexperience project, which the maintainer creates for this upload and deletes straight after; uv publish reads it from UV_PUBLISH_TOKEN. The Go modules need only their tags, at the verified commit: a tag that already exists there is kept, and one that exists at any other commit stops the command.

First, in the same shell, the versions, derived from Directory.Build.props as release.yml's derive_versions derives them (scripts/release-version.sh; no suffix: the same version in every language; preview.N: Python aN), then the distribution, built once and refused unless pyproject.toml carries the derived version:

version="$(scripts/release-version.sh dotnet)"; python="$(scripts/release-version.sh python)"; go="$(scripts/release-version.sh go)"
echo "NuGet $version, Python $python, Go $go"

( declared="$(sed -nE 's/^version = "([^"]+)"$/\1/p' python/pyproject.toml | head -n 1)"
  if [ -z "${verified:-}" ] || [ "$(git rev-parse HEAD)" != "$verified" ]; then
    echo "FAILED: HEAD is not the commit steps 1-9 verified ($verified); re-run the checks"; false
  elif [ "$declared" != "$python" ]; then
    echo "FAILED: python/pyproject.toml says $declared, but Directory.Build.props versions this commit as $version (expected $python)"; false
  else
    cd python && rm -rf dist && uv build --out-dir dist && rm -f dist/.gitignore && ls dist \
      && echo "Built agenticexperience $python" || { echo "FAILED: see above"; false; }
  fi )

Then the upload and the Go tags. This uploads the files just built, never a rebuild, so it is safe to run again after a partial failure: --check-url skips the files PyPI already has, and tags already at the commit are kept.

( if [ ! -f "python/dist/agenticexperience-$python.tar.gz" ] || [ ! -f "python/dist/agenticexperience-$python-py3-none-any.whl" ]; then
    echo "FAILED: python/dist does not hold agenticexperience $python; run the build above first"; false
  else
    uv publish --check-url https://pypi.org/simple/ "python/dist/agenticexperience-$python.tar.gz" "python/dist/agenticexperience-$python-py3-none-any.whl" \
      && for module in go go/inmemory go/postgres go/postgres/pgtest go/maf go/telemetry; do
           tag="$module/$go"
           git rev-parse -q --verify "refs/tags/$tag" > /dev/null || git tag "$tag" "$verified" || exit 1
           [ "$(git rev-parse "$tag^{commit}")" = "$verified" ] || { echo "FAILED: $tag exists at another commit"; exit 1; }
           git push origin "refs/tags/$tag" || exit 1
         done \
      && echo "Published agenticexperience $python and tagged the Go modules at $go" || { echo "FAILED: see above; running this again skips what is already done"; false; }
  fi )

Then confirm the Go modules on the proxy: go list -m "github.com/fabbrik/AgentExperience.NET/go/maf@$go" must print that version.

After the release: move the package-validation baseline

Not a release check: a follow-up pull request, once the release is out. When nuget.org lists all eight packages at the new version (it can take an hour after the push; until then a restore of that version fails with NU1102), set AgentExperiencePackageValidationBaseline in Directory.Build.props to it, delete every src/*/CompatibilitySuppressions.xml (they declared breaks against the previous release, which the new baseline already contains), and remove DisablePackageBaselineValidation from a package that has just shipped for the first time. Restore again before packing: the new baseline has to be downloaded. Until the next release, packing compares each package with the published package of the same version; that is intended, and it passes while nothing has broken. Forgetting the move is caught when the next version's CHANGELOG section is added: the release test then finds a release between the baseline and the version being built, and release.yml runs it before it packs.

# Run before the move: the version just published is still the one Directory.Build.props builds.
( version="$(scripts/release-version.sh dotnet)"
  ok=true
  for project in src/*/*.csproj; do
    id="$(basename "$project" .csproj | tr '[:upper:]' '[:lower:]')"
    index="$(curl -fsS "https://api.nuget.org/v3-flatcontainer/$id/index.json")" || { echo "FAILED: could not read $id from nuget.org"; ok=false; continue; }
    grep -qF "\"$version\"" <<<"$index" && echo "listed: $id $version" || { echo "NOT YET: $id $version"; ok=false; }
  done
  $ok && echo "All packages listed: move the baseline to $version" || echo "FAILED: wait, then run this again" )

# Run after the move, before opening the pull request.
( baseline="$(sed -nE 's/.*<AgentExperiencePackageValidationBaseline>([^<]+)<.*/\1/p' Directory.Build.props)"
  version="$(scripts/release-version.sh dotnet)"
  left="$(find src -mindepth 2 -maxdepth 2 -name CompatibilitySuppressions.xml; grep -l DisablePackageBaselineValidation src/*/*.csproj)"
  if [ "$baseline" != "$version" ]; then echo "FAILED: the baseline is $baseline, the published version $version"
  elif [ -n "$left" ]; then echo "FAILED: still declared against the previous release: $left"
  else echo "Baseline OK: $baseline"; fi )