AGENT SKILL

release

Releases .NET NuGet packages through a layered chain (library, MSBuild SDK, analyzers, consumers) without breaking restore. Use when publishing a package, bumping a lower-layer dependency in its consumers, moving a .NET SDK pin across repositories, choosing tag-driven versus push-driven publishing, setting up NuGet trusted publishing, or waiting for nuget.org to index a version before consumers restore it.

License 许可
Apache-2.0
最近更新
2026-11-10
Stars
★ 1
Forks
0

01 前言 Front Matter

name
release
license
Apache-2.0
description
Releases .NET NuGet packages through a layered chain (library, MSBuild SDK, analyzers, consumers) without breaking restore. Use when publishing a package, bumping a lower-layer dependency in its consumers, moving a .NET SDK pin across repositories, choosing tag-driven versus push-driven publishing, setting up NuGet trusted publishing, or waiting for nuget.org to index a version before consumers restore it.
compatibility
Needs git, gh, curl and the .NET SDK. scripts/wait-nuget.sh is POSIX shell.

02 资源文件 1

03 SKILL.md 正文

Layered NuGet release

A consumer can only restore a version nuget.org has indexed. Pointing a version variable (SDK truth, Version.props, global.json msbuild-sdks) at a version that isn't published and indexed fails every restore with NU1102. Release order follows the dependency graph, lowest layer first, and each layer waits for the one below it.

ANcpLua chain (lowest first):

ANcpLua.Roslyn.Utilities -> ANcpLua.Analyzers -> ANcpLua.NET.Sdk (injects the analyzers) -> consumers

Two relations point in opposite directions, and both are true. For publishing the analyzers come before the SDK, as drawn above. For building, the analyzer repository uses the SDK, which is why its own agent contract draws Roslyn.Utilities -> NET.Sdk -> Analyzers.

The SDK's Version.props names the analyzer version every consumer gets, so the analyzers publish before the SDK points at them. The analyzer repository itself builds with the last published SDK (a deliberate one-version lag that breaks the cycle), and its self-reference variables point at its own last published version, never the one being built. Consumers move last, through global.json msbuild-sdks.

1. Before touching versions

  • Read how each repository publishes (.github/workflows/*publish*.yml, release.sh, Makefile):
    • Tag-driven: on: push: tags: ['v*']. You create and push the tag.
    • Push-driven: on: push: branches: [main]. CI bumps the patch from the latest v* tag and creates the tag itself. Don't tag by hand.
    • Manual: a release.sh with an API key read from a file. Run it from a clean tree.
  • Look for a publish gate ("no publishable changes since <tag> — skipping"). A commit that changes only global.json, docs or CI is often skipped on purpose. Don't force an identical package through it.
  • The new version string must not exist yet: curl -s https://api.nuget.org/v3-flatcontainer/<id-lowercase>/index.json.

2. Release one layer

  1. Make the change, update CHANGELOG.md and anything else that names the old version: docs, templates, global.json, Version.props. Search for the old value across the repository.
  2. Run the repository's build, pack and test entrypoints the way CI does. For MSTest execution, invoke the installed mstest-extensions:mstest skill; if unavailable, report that gap and retain the repository's documented test entrypoint. A broken commit must never reach a publishing branch or tag.
  3. Commit, push, then tag if publishing is tag-driven: git tag vX.Y.Z && git push origin vX.Y.Z.
  4. Watch the publish run: gh run list --workflow <file> --limit 1, then gh run watch <id>.
  5. Wait for the index with scripts/wait-nuget.sh <PackageId> <version>. It requires both the flat container, which restore uses, and the registration leaf, which PackageMetadataResource and many tools use. The flat container goes live first, often minutes before the registration leaf.
  6. Only then point the next layer at the new version.

A tag that points at a broken commit is never moved or deleted on the remote. Release the next patch instead.

Pack before tests in CI. dotnet pack --no-build ships whatever sits in the build output when it runs, and a test that builds or packs the repository's own projects (package-consumption tests, MSBuild integration tests) writes into that same output unless it gets its own -p:ArtifactsPath=<temp>/. ANcpLua.Roslyn.Utilities 3.0.0 and 3.0.1 shipped AssemblyVersion 0.0.0.0 that way: a test packed src/ with VersionPrefix=0.0.0 between build and pack. After packing, check one assembly per package: the version inside must be the release version. A green build plus correct .nupkg file names doesn't prove it.

3. NuGet client caching

The NuGet client caches HTTP responses for 30 minutes (~/.local/share/NuGet/http-cache). A tool that queried a package before its version was indexed keeps answering "not found" after the index catches up. Re-run it with a throwaway cache:

NUGET_HTTP_CACHE_PATH="$(mktemp -d)" dotnet run --project tools/Generator

dotnet restore --no-http-cache does the same for restore. Don't clear the user's caches to get past this.

4. Publishing credentials

Order of preference:

  1. Trusted publishing (OIDC). The workflow has permissions: id-token: write and a NuGet/login step that exchanges the GitHub token for a short-lived API key (steps.login.outputs.NUGET_API_KEY), configured on nuget.org per package owner, repository and workflow file. There's no long-lived secret to rotate. The workflow file name is part of the policy, so renaming the workflow breaks publishing.
  2. A scoped API key in a CI secret. Glob-scoped to the package prefix, push-only, with an expiry.
  3. A manual key file for local release.sh runs. Read from a file whose location the credential registry records (vitals keys on ANcpLua machines). Never paste a key into a chat, a commit or a command line that ends up in shell history.

When a publish fails with 403, check the key's glob and expiry, or the trusted-publishing policy's repository and workflow name, before retrying.

5. Moving consumers

For each consumer repository in the chain:

  1. global.json: msbuild-sdks to the new SDK version, sdk.version to the agreed .NET SDK.
  2. Remove repo-local overrides that the new SDK truth made equal or stale (see the nuget-versions skill, section 1).
  3. Direct dependencies on lower layers (for example ANcpLua.Roslyn.Utilities) go to the new version in their single central place. Read the release notes for moved or split packages.
  4. Build and test, commit, push, then release according to that repository's own mechanism.
  5. A repository with uncommitted work by someone else: work in a separate git worktree on origin/main, so the release commit contains only the version change.

6. .NET SDK pins across machines

  • Install a new SDK through the machine's own channel (a dotfiles target, a package manager, or dotnet-install.sh --install-dir <the existing root>). Keep normal machine selection predictable. If an isolated preview is requested, invoke the available ancplua-dotnet:nuget-versions skill for SDK selection. Without it, report the missing guidance rather than changing machine PATH or the stable release pin.
  • macOS: if an installer overwrites the dotnet host binary in place while the old one is still mapped, the kernel kills every new dotnet process (exit 137, "Killed: 9") because the cached code signature no longer matches the file. Delete the host binary and re-run the installer so the file is created fresh. Don't patch the signature.
  • CI uses actions/setup-dotnet with global-json-file: global.json, so the pin is the single source.

7. Report

For every layer, give the repository, commit, tag or version, publish run conclusion and index status, and for consumers the files changed. A layer whose gate skipped publishing is reported as "committed, publish skipped by gate (<reason>)", not as released.

04 同仓库更多 Skills

ANcpLua
ANcpLua/ancplua-dotnet

csharp-union-types

Design, review and implement C# 15 unions and closed hierarchies in .NET 11 code. Use for union declarations, custom [Union] types, exhaustive matching, default/null handling and union serialization. Do not upgrade earlier frameworks or replace working inheritance merely because unions exist.

★ 1
ANcpLua
ANcpLua/ancplua-dotnet

performance

Investigate .NET runtime performance using logs, metrics, traces, spans and profiles; collect crash/hang diagnostics. Use for CPU, GC, allocation or latency problems, hot-path reviews and BenchmarkDotNet comparisons. MSBuild timing belongs to msbuild; MSTest execution belongs to mstest-extensions.

★ 1
ANcpLua
ANcpLua/ancplua-dotnet

nuget-versions

Manage .NET package and SDK versions, CPM migrations, Version.props ownership, global.json pins, isolated SDK installations and Renovate updates. Use for package bumps, conflicting or missing versions, NuGet restore errors and SDK selection. MSTest runner/profile semantics belong to mstest-extensions.

★ 1
ANcpLua
ANcpLua/ancplua-dotnet

msbuild

Writes and reviews MSBuild evaluation, properties, items, imports, custom targets and build/buildTransitive package assets for SDK-style .NET repositories. Use for ignored or empty properties/items, generated files, analyzer/build-asset packaging, build-file reviews, binlog diagnosis and incremental-build problems. Focused MSTest project setup, runner configuration and test commands belong to mstest-extensions.

★ 1
ANcpLua
ANcpLua/ancplua-dotnet

csharp-refactoring

Refactor C# and reconcile stale constants, dead checks and abandoned code, including indirect production uses. Use for renames, moves, deduplication, exhaustive cleanup, generated declarations and runtime/API contracts. MSTest test design and review belong to mstest-extensions.

★ 1
ANcpLua
ANcpLua/ancplua-dotnet

audit

Audits one or more .NET repositories for build, package and analyzer problems and separates certain fixes from judgment calls. Use for repository or fleet build-policy audits, shared SDK/package consistency and cross-repository version rollouts. Focused MSTest setup, execution and test-quality reviews belong to mstest-extensions.

★ 1