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.