OpenNest/docs/releasing.md

Windows releases

GitHub (ajisaacs/OpenNest) is the primary repository: push branches and tags there. Gitea (git.thecozycat.net/aj/OpenNest) is a read-only backup that pulls from GitHub every hour; it refuses pushes.

Build a candidate

1. Choose a committed source revision; never include uncommitted work implicitly.
2. Push a release/vX.Y.Z branch containing the release workflow to GitHub. The pushing credential needs Contents: read/write, plus Workflows: read/write to introduce or update .github/workflows files. Do not change credentials or broaden permissions without the owner's approval.
3. The Windows release build workflow uses a GitHub-hosted windows-2022 runner. It builds the solution, runs all four test projects in Release and the main test project in Debug, then packages and smoke-tests the desktop app. Optional local/proprietary fixture and opt-in measurement tests may skip; inspect the uploaded TRX files rather than treating skips as passes.
4. Download the OpenNest-X.Y.Z-win-x64 artifact and verify its .sha256. It contains OpenNest.vX.Y.Z.win-x64.zip, with the .NET runtime, native dependencies, shipped configurations, all three post-processors, license, and build-info.json identifying the exact source commit. The nesting engines are built into OpenNest.Engine.dll; no external engine repository or plug-in DLL is packaged. scripts/ReleaseSmoke loads the packaged engine assembly and checks that every built-in engine instantiates from it, that the renamed Opus55NestingEngine selection resolves to Irregular, and that an unknown engine name is rejected.

The workflow has read-only repository permissions and does not publish releases. Once present on the default branch, it can also be dispatched manually with an X.Y.Z version. Running/dispatching via a PAT needs suitable Actions permissions; public run metadata alone does not prove dispatch access.

For a local Windows build with PowerShell 7 and the .NET 8 SDK:

./scripts/Publish-Windows.ps1 -Version X.Y.Z

Run the test suites separately before local packaging. The script refuses an existing output directory; use a fresh -OutputDirectory rather than deleting previous packages. CI also exercises this refusal and verifies the ZIP is unchanged.

Publish

Review release notes, breaking API changes, and known limitations with the owner. After the candidate passes, integrate the release tooling into the chosen branch, create an annotated vX.Y.Z tag on the exact release commit and push it to GitHub. Use the successful tag build's artifacts for the GitHub Release; do not substitute packages built from another commit. Verify the public asset names, sizes, download/checksum, and release status after upload. Do not overwrite an existing release/tag or asset silently.

The automated desktop smoke test proves the extracted app opens its main window and discovers posts. It does not replace interactive CAD/nesting acceptance, physical CNC/serial verification, GPU execution, or real-model ONNX accuracy. Packages are unsigned; code signing and a fuller packaged-post execution test remain follow-up hardening.

Server image (separate from Windows candidates)

Server image validates relevant PRs and master pushes without registry login, package-write permissions, or registry upload. It builds/tests with .NET 8, records pinned SDK/runtime base digests, builds a single-platform linux/amd64 image without cache or attestations (--provenance=false --sbom=false), and runs the real-client container persistence/backup/restore smoke. A Windows v* tag build alone never publishes a server image.

Publication requires owner-approved release intent: a published GitHub Release or an explicit Server image dispatch from master, naming an existing strict vX.Y.Z tag (no prerelease, leading zero, or extra suffix). The tag must resolve to a full commit already on master. For a published Release, that peeled commit must also equal the event's full GITHUB_SHA; a retargeted tag is refused. Manual dispatch intentionally resolves the approved existing tag, not the workflow's master SHA. The job checks out that exact source, reruns all server/image gates, and pushes the same smoked image to ghcr.io/ajisaacs/opennest-server:X.Y.Z and :sha-<full-commit> only. Both tags must be absent; retries after even a partial upload stop instead of overwriting. There are no latest, major, or minor aliases. Do not dispatch just to test publication.

Publication requires an existing owner-verifiable private package, linked to ajisaacs/OpenNest, with repository Actions access (normally inherited from the link). The job uses only its scoped GITHUB_TOKEN. All package metadata 404s are refused: GitHub can mask an inaccessible private package as Not Found. Opaque registry token success, an empty tag list, or a registry 404 proves neither package absence nor privacy and cannot override the metadata check. Explicit reduced scope and failed registry read access also stop the job. The job rechecks private association after upload.

First-package initialization is a separately owner-authorized prerequisite outside this workflow. Until the private package, repository link, and Actions access can be verified, publication remains blocked while read-only validation can pass. There is no automatic bootstrap, extra PAT, absence assertion, or bypass setting. A local credential's Packages API 403 proves neither absence nor privacy. No workflow changes visibility. Public availability needs separate owner approval and a later anonymous-pull check; it is not approved here.

The local gate reads docker image save to hash the actual config and verify each layer against its ordered uncompressed rootfs digest. It rejects unexpected indexes/attestations. Smoke and tagging use the inspected immutable Docker ID, not a mutable local tag, and readback must match that pre-smoke identity. Success requires exact readback of both manifest digests, linux/amd64, OCI labels, config bytes, and the full layer/rootfs chain identifying that same smoked image. A separate clean job pulls the returned manifest digest, independently checks its saved config/layers, and repeats the real-client smoke using tools checked out from that source commit. Only its pass verifies the image.

Artifacts retain TRX, explicit logs, and safe provenance. Docker's store-dependent Id, the config blob digest, and the registry manifest digest are separate values: classic Docker may use the config digest as Id, while containerd may use a manifest or index digest. Disabling attestations does not make Id a config digest. Temporary image-save archives are deleted, never uploaded. Artifacts never include smoke state JSON, databases, nest archives, Docker auth configs, or credentials. A failed publication/verification is not a release acceptance; inspect its logs and any partial tags with the owner before choosing a new approved version.

For a local read-only check of the release guards:

python3 -m unittest discover -s scripts -p test_server_image_release.py -v

Deployment is deliberately separate; use the verified digest and the private pull/Compose procedure. No publication, release creation, deployment, or visibility change is implied by adding or validating this workflow.