Files
OpenNest/docs/releasing.md
T
aj 04c0e3bca3 fix(server-ci): recognize GitHub's real package-not-found response
The first v0.7.0 publish stopped at preflight because GitHub answers a
missing user package with 404 "Package not found." (documentation_url
.../rest/packages/packages#get-a-package-for-a-user), while the check
only accepted "Not Found", a shape the tests had assumed. Accept that
message too, require the packages documentation URL, and pin the real
body in the tests. Other 404 shapes still stop the job, and the registry
must still report the repository unknown.
2026-11-17 19:51:52 -05:00

152 lines
9.0 KiB
Markdown

# 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 six test projects in Release and
the main test project in Debug, then packages and smoke-tests the desktop app.
A test that is silent for five minutes is killed and named in the log, with a
mini dump in the uploaded `windows-test-results` artifact. The release job
installs a SHA-256-pinned Poppler Windows binary for PDF text/column tests;
the runner's older `pdftotext` lacks the required `-bbox` option.
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,
the `Help` folder from the opennest-help release pinned in `scripts/help.json`
(see [desktop help](desktop-help.md)), and `build-info.json` identifying the exact
source commit and help version. The nesting engines
are built into `OpenNest.Engine.dll`; no external engine repository or plug-in
DLL is packaged. Its `velopack/` folder holds the self-updating packages built
from the same folder; see [desktop auto-update](auto-update.md#release-packages). `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. The separate [development build](auto-update.md#development-builds)
workflow does replace the rolling `dev-build` pre-release after each green master
push; it is not a release and never touches `vX.Y.Z` tags. 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:
```powershell
./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.
Upload the plain ZIP, its `.sha256`, `OpenNest.vX.Y.Z.velopack.sha256` and all five
files in `velopack/` as release assets, keeping their names. Installed copies update
only from the newest full (non-pre-release) Release that carries
`releases.win.json` and its `-full.nupkg`; a full Release without them leaves every
installation on its current version.
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 an explicit, owner-approved `Server image` dispatch **from
`master`**, naming an existing strict `vX.Y.Z` tag (no prerelease suffix, leading
zero, or extra suffix). Publishing a GitHub Release, stable or pre-release, only
validates the image; it never publishes it, so a desktop release and a server image
release are separate decisions. The tag must resolve to a full commit already on
`master`. The 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.
The image is **public** (owner decision): the source repository is public, and
anyone may pull the image without a GitHub login. Publishing it does not make a
server reachable; the server has no authentication and stays on a trusted LAN
(see [nest storage](nest-storage.md#deploying-with-compose)).
The job builds, tests and smokes the tag's own tree, but the publication policy
(preflight before upload and readback after it) always comes from `master`'s copy
of `scripts/server_image_release.py`, so an older tag publishes under the current
policy. The job uses only its scoped `GITHUB_TOKEN`. An existing package must be public
and linked to `ajisaacs/OpenNest`; a private package or one linked to another
repository stops the job before upload. The first publication creates the
package: GitHub's own package-not-found response is accepted only when the
registry also reports the repository unknown, because a package hidden from the
token still has a registry repository. Every other metadata error, denial,
reduced registry scope or failed tag-list read stops the job. Because the source
repository is public and the image carries its `org.opencontainers.image.source`
label, the new package is linked to the repository and public. The job rechecks
public visibility and association after upload, and the clean-runner
verification pulls the returned digest **without logging in**, which proves
anonymous pulls work.
If a first publication fails that recheck (the package came out private), the two
tags are already uploaded and a retry refuses them: in the package settings make
it public and confirm the anonymous pull by hand, or delete the package and
dispatch again. There is no extra PAT or bypass setting, and no workflow changes
visibility.
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:
```sh
python3 -m unittest discover -s scripts -p test_server_image_release.py -v
```
Deployment is deliberately separate; use the verified digest and the
[pull/Compose procedure](nest-storage.md#deploying-with-compose). No
publication, release creation, deployment, or visibility change is implied by
adding or validating this workflow.