Releasing
Local package feed
Before relying on a NetPrints change from another project, pack it locally instead of waiting for a release — a restore can never silently prefer or fall back to a published package, because every local pack gets its own version:
ver=$(scripts/pack-local.sh --print-version) # packs everything into local-packages/
scripts/verify-packages.sh local-packages "$ver" # metadata, tool install, a fresh HelloWorld
local-packages/ is git-ignored (kept only through .gitkeep, because NuGet fails a restore with
NU1301 when a configured local source does not exist). Point another project at it with:
<PackageReference Include="NetPrints.Sdk" Version="0.1.0-local.20260101000000" PrivateAssets="all" />
and a nuget.config that lists the absolute path to local-packages/, or:
dotnet tool install -g NetPrints.Cli --version 0.1.0-local.20260101000000 --add-source /path/to/local-packages
Release process
A release is a pushed tag matching v* (for example v0.1.0). .github/workflows/release.yml:
pack— restores, computes the version with MinVer,dotnet packs 9 packages (16 files, package validation on), and runsscripts/verify-packages.shagainst them.desktop— publishes the self-contained editor forlinux-x64,win-x64andosx-arm64. Smoke-testslinux-x64andosx-arm64withscripts/smoke-desktop.sh;win-x64hassmoke: false. Archives each withscripts/archive-desktop.sh(.tar.gzfor Linux/macOS,.zipfor Windows).assets— collects every package and archive, and writesSHA256SUMS.txt.publish-nuget— pushes the packages to nuget.org with Trusted Publishing (OIDC; no stored API key). Tag pushes only.github-release— creates the GitHub Release from.github/release.yml's categories and.github/release-notes.md, and attaches build provenance attestations. Tag pushes only.
workflow_dispatch and a pull request that touches the release inputs (this workflow, the release
scripts, eng/, the Directory.*.props files or a src/**/*.csproj) run the same workflow as a
dry run: pack, desktop and assets run and their artifacts (including SHA256SUMS.txt) can
be downloaded and verified, but publish-nuget and github-release are skipped, no secrets are
read, and nothing is published. Never push a v* tag, run dotnet nuget push, or set
PUBLISH_DOCS/PUBLISH_WIKI to test this — the dry run already exercises the whole pipeline.
The docs site (this site, plus the API reference) and
the wiki build the same way, from .github/workflows/docs.yml and .github/workflows/wiki.yml, but
publish independently of package releases — see the owner steps below.
Release step: pin keys
Before tagging a release of a project that tracks pin keys (NetPrints.Core: src/NetPrints.Core/NodePins.*.txt),
move the lines of NodePins.Unshipped.txt into NodePins.Shipped.txt, in the same sorted order: a line
<kind> <direction>.<exec|data|type>.<key> is added, and a *REMOVED*<line> line deletes the matching shipped line.
Leave only the header comment in the unshipped file. Commit it with the version bump, so the next release starts with
every key it ships recorded (NPA010) and none missing (NPA011).
Release step: package validation baselines
Every packable library sets EnablePackageValidation, so dotnet pack compares its public surface with the last
published version and fails on an unrecorded break. Libraries already on nuget.org (NetPrints.Core,
NetPrints.Reflection, NetPrints.Catalog) set PackageValidationBaselineVersion to $(NetPrintsPackageBaselineVersion),
which Directory.Build.props defines once, and a CompatibilitySuppressions.xml next to the project holds exactly
the intended breaks since it (generate it with -p:ApiCompatGenerateSuppressionFile=true). PackageValidationTests
checks that only CP0002 and CP0009 are suppressed, each against the *REMOVED* lines of
PublicAPI.Unshipped.txt or the sealed types; a suppression with another id fails until a cross-check for it exists.
A package that has never been published (NetPrints.Serialization, NetPrints.Extensibility.Abstractions and
NetPrints.Extensibility before 0.4.0) has no baseline. In the release that first publishes it, add
<PackageValidationBaselineVersion>$(NetPrintsPackageBaselineVersion)</PackageValidationBaselineVersion> to its
project in the next change after the tag, and list the package in PackageValidationTests.Published. After each
release, set NetPrintsPackageBaselineVersion to the version just published (the only edit that moves the baseline)
and delete the CompatibilitySuppressions.xml files: the recorded breaks belong to the release that made them. The
tests stay green with the files gone. The baseline must be the last version that is on nuget.org: do not move it to
0.3.0 until that version is published.
Owner one-time steps
None of these are needed to open or merge a PR: every workflow tolerates them being undone. The
gated jobs either skip (an unset vars.*) or fail with a message naming the missing step (an unset
NUGET_USER).
- nuget.org Trusted Publishing — on nuget.org, add a Trusted Publishing policy for owner
danielmeza, repositorynetprints, workflow filerelease.yml, environmentrelease. Then set the repository (orreleaseenvironment) secretNUGET_USERto the nuget.org profile name (not the email). Optionally reserve theNetPrints.package ID prefix. releaseenvironment — create it under Settings → Environments, optionally with required reviewers and av*deployment tag rule.- GitHub Pages — Settings → Pages → Source = GitHub Actions; then set the repository variable
PUBLISH_DOCS=true. The next push tomaster(or a manual Docs run) deploys the site, and from then on the$schemaURL in generated.netpcfiles resolves. - Wiki — enable it under Settings → Features → Wikis (restricted to collaborators), create its
first page in the web UI, then set
PUBLISH_WIKI=true. - Labels —
gh label create breaking-change --color B60205 --repo danielmeza/netprintsandgh label create ignore-for-release --color EDEDED --repo danielmeza/netprints. - First release (after this work is merged, not part of it) —
git tag v0.1.0 && git push origin v0.1.0.