From 459e7d839cfb185d36e146943aec026da1d11a19 Mon Sep 17 00:00:00 2001 From: Rex Morgan Date: Thu, 6 Aug 2026 20:51:08 -0400 Subject: [PATCH] docs: document the NuGet release process in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Derived from reading .github/workflows/release.yml and gh release history while cutting 2.4.1 — record it so it doesn't need re-deriving each time: the version comes entirely from the published GitHub Release's tag name (no file to bump), only a *published* Release triggers the workflow, and publishing is irreversible so the merge/CI state should be confirmed first. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8d42529e..252fd57f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,3 +16,41 @@ Name test files and classes after the **capability or use case** under test (e.g Issue numbers are meaningless once the bug is fixed; the capability is what matters long-term, and grouping by capability keeps related coverage discoverable together instead of scattered across one-off files. + +## Release process + +Publishing to NuGet is irreversible — a bad push can't be unpublished, only +deprecated. Don't skip the verification steps below to save time. + +1. **The version comes from the GitHub Release's tag, not from any file in + the repo.** `.github/workflows/release.yml` triggers on `release: + published` and packs with + `/p:version=${{ github.event.release.tag_name }}`. There is no version to + bump in `Directory.Build.props` or any `.csproj` — creating and + *publishing* the GitHub Release is the entire release action. A tag + pushed without a published Release does nothing. +2. **Tag format has no `v` prefix** — `2.4.0`, `2.4.1`, not `v2.4.0`. Check + the current version with `git tag --sort=-creatordate | head -1` or + `gh release view --json tagName`. +3. **Before creating the release**, confirm the intended commit is actually + on `master` (`git log --oneline -1 origin/master`) and that CI passed for + whatever merged it — don't race a merge that's still running checks. +4. **Bump per semver** based on what's actually in the diff since the last + tag: patch for bug fixes only, minor for additive features, major for + breaking changes. Regression fixes for bugs introduced after the last + release (i.e. the last release itself shipped broken) are still a patch + bump, not a reason to skip versioning. +5. **Create and publish in one step** with + `gh release create --title --notes-file ` (omit + `--draft` — a draft does not trigger the workflow; only the `published` + event does). Write release notes in the style of prior releases (see + `gh release view 2.4.0 --json body`): grouped sections (Fixes / New + features / Performance / Compatibility notes), one bullet per PR with a + `(#NNN, fixes #NNN)` reference, a Contributors line, and a + `Full Changelog` compare link + (`https://github.com/Handlebars-Net/Handlebars.Net/compare/...`). +6. **After publishing**, watch the `Release` workflow run + (`gh run list --workflow=release.yml --limit 1`) through to completion — + it signs the assembly and pushes to NuGet via trusted OIDC publishing, and + a failure partway through (e.g. signing) needs to be caught, not assumed + to have succeeded because the Release object exists.