Skip to main content

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:

  1. pack — restores, computes the version with MinVer, dotnet packs 9 packages (16 files, package validation on), and runs scripts/verify-packages.sh against them.
  2. desktop — publishes the self-contained editor for linux-x64, win-x64 and osx-arm64. Smoke-tests linux-x64 and osx-arm64 with scripts/smoke-desktop.sh; win-x64 has smoke: false. Archives each with scripts/archive-desktop.sh (.tar.gz for Linux/macOS, .zip for Windows).
  3. assets — collects every package and archive, and writes SHA256SUMS.txt.
  4. publish-nuget — pushes the packages to nuget.org with Trusted Publishing (OIDC; no stored API key). Tag pushes only.
  5. 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).

  1. nuget.org Trusted Publishing — on nuget.org, add a Trusted Publishing policy for owner danielmeza, repository netprints, workflow file release.yml, environment release. Then set the repository (or release environment) secret NUGET_USER to the nuget.org profile name (not the email). Optionally reserve the NetPrints. package ID prefix.
  2. release environment — create it under Settings → Environments, optionally with required reviewers and a v* deployment tag rule.
  3. GitHub Pages — Settings → Pages → Source = GitHub Actions; then set the repository variable PUBLISH_DOCS = true. The next push to master (or a manual Docs run) deploys the site, and from then on the $schema URL in generated .netpc files resolves.
  4. Wiki — enable it under Settings → Features → Wikis (restricted to collaborators), create its first page in the web UI, then set PUBLISH_WIKI = true.
  5. Labels — gh label create breaking-change --color B60205 --repo danielmeza/netprints and gh label create ignore-for-release --color EDEDED --repo danielmeza/netprints.
  6. First release (after this work is merged, not part of it) — git tag v0.1.0 && git push origin v0.1.0.