binarylane-dotnet/docs/releasing.md

Maintainer guide: releases

This page is for package maintainers.

This repository publishes packages with NuGet trusted publishing and GitHub OpenID Connect (OIDC). It must not use a long-lived NuGet API key.

One-time setup

1. On NuGet.org, create or verify the trusted-publishing policy:
   • publisher: GitHubActions;
   • GitHub owner: alexhopeoconnor;
   • repository: binarylane-dotnet;
   • workflow: publish.yml;
   • environment: release.
2. In GitHub, create a protected environment named release and require a maintainer approval.
3. Create a protected release environment secret named NUGET_USER with the NuGet.org username alex.hope.oconnor. It is an identifier, not an API key.
4. Protect main with CI and restrict creation of v* tags.

The first successful OIDC publication must occur before NuGet's policy activation window expires. After success, NuGet permanently activates the policy for this exact repository/workflow/environment identity.

Release checklist

1. Review BinaryLane contract changes and update the committed snapshot if necessary.
2. Update code, tests, docs, API coverage, and CHANGELOG.md.
3. Set the package <Version> to the intended SemVer release.
4. Open and merge the release pull request after CI succeeds.
5. Tag the exact merge commit. The tag must equal the package version with a leading v.

git tag -a v0.1.0-beta.1 -m "BinaryLane.Api 0.1.0-beta.1"
git push origin v0.1.0-beta.1

6. Approve the protected release environment in GitHub Actions.
7. Verify the package page, rendered README, icon, license, repository link, symbols, package ownership, and GitHub Release.

What the release workflow does

publish.yml validates the tag, package version, and changelog heading; it then restores, builds, tests, packs, and compiles the maintained demo against the resulting local .nupkg. Only then does NuGet/login@v1 exchange the GitHub OIDC identity for a short-lived one-time publish key. The key is used only in memory by the job.

The GitHub Release job runs after NuGet publishing and receives no OIDC permission. It attaches the package files and uses the matching changelog section for release notes.

Recovery

NuGet packages cannot be overwritten. If a published release has a packaging defect, unlist it if appropriate, publish a new version, and document the correction in the changelog. A tag can be replaced only before the workflow publishes its matching NuGet version; published package versions are never reused.