Make the release pipeline testable before a tag (dry-run + auto rehearsal)

[Reefact]

Summary

release.yml is the only workflow no CI run exercises before a real tag — version resolution, pack, SBOM generation, OIDC and the attestation permissions only ever execute in production, on a tag, once. Several defects were found here that were invisible from the repository (the +metadata regex, the nuget.org re-signing mismatch, the dispatch-tag target). This makes the pipeline testable two complementary ways, split by side effect, with the packing logic single-sourced so the rehearsal cannot drift, and documents the manual path.

1. a manual dry-run in release.yml that runs everything up to and including the attestation (the near-real rehearsal, on demand);
2. an automatic dry-run workflow that runs the side-effect-free portion (build + pack + SBOM) on every PR and push to main;
3. a shared pack script both workflows call, so the dry-run can never diverge from the real release;
4. maintainer documentation (EN + FR) for the manual dry-run.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactoring
• Analyzer / diagnostic change
• Tests
• Documentation
• Build / CI / tooling

Changes

tools/packaging/pack.sh — single source of truth (new)

• packs the two published projects with GenerateSBOM=true and then asserts the SPDX manifest is embedded in each .nupkg. Both release.yml and release-dryrun.yml call it — the same pattern the repo already uses for commit-lint (one script shared by the hook and CI), so the dry-run cannot drift from the real release, and the real release gains the SBOM-present check too. (Named packaging/ because the .gitignore [Rr]elease/ rule would ignore tools/release/.)

.github/workflows/release.yml — manual dry-run mode

• new dry_run boolean input on workflow_dispatch, defaulting to true so an accidental dispatch publishes nothing — publishing requires explicitly unticking it;
• the Pack step now calls tools/packaging/pack.sh;
• a dry run executes everything up to and including the provenance attestation (deliberately — OIDC/permission failures are exactly the class it rehearses) and skips the three publish steps (NuGet login, push, GitHub Release), gated on github.event_name == 'push' || inputs.dry_run == false, so a tag push always publishes — the normal release path is unchanged.

.github/workflows/release-dryrun.yml — automatic rehearsal (new)

• runs on every push to main, every PR, and workflow_dispatch; contents: read only — no OIDC, no attestation, none of release.yml's write scopes;
• builds the solution, then calls the same tools/packaging/pack.sh; deliberately stops before every side-effecting step (no attestation, no NuGet push, no GitHub Release).

maintainers/ — documentation (new)

• ReleaseDryRun.en.md + ReleaseDryRun.fr.md: pedagogical, bilingual maintainer doc for the manual dry-run (purpose, per-step table, how to run it, impacts — notably that the attestation does run and writes a permanent public record). In a new top-level maintainers/ directory, deliberately separate from doc/ (the library's user documentation).

Testing

• dotnet build FirstClassErrors.sln
• dotnet test FirstClassErrors.sln
• Analyzer tests pass (FirstClassErrors.Analyzers.UnitTests)

The automatic dry-run validates itself on this PR (it triggers on pull_request). The shared script was also rehearsed locally on the .NET 10 SDK under the CI warning ratchet: build green (0 warnings), both projects pack via tools/packaging/pack.sh, and the SBOM-present check passes (exit 0). YAML and POSIX-sh syntax both validate.

The release.yml manual dry-run remains CI-only by nature (it needs OIDC); its first workflow_dispatch run after merge is the proof — e.g. version 0.0.0-dry.1, dry_run ticked. Neither path can exercise the actual NuGet push / repository-signed bytes; only a real release does.

Documentation

• No library documentation change required (the new maintainers/ doc is operational/maintainer documentation, kept separate from doc/).

🤖 Generated with Claude Code

https://claude.ai/code/session_01AbXi2ZEaUFeFWodNxdY6Zk