Skip to content

Development Releases

smallketchup82 edited this page Oct 29, 2026 · 3 revisions

Authenticate once using gh auth login and prepare the development environment. The normal release path builds locally, reuses caches, and opens an unpublished draft in GitHub. It does not ask for a version or publish automatically.

Build locally and create a draft

Build and prepare a release locally with one command:

./scripts/create-release.py --iterm

Authenticate once with gh auth login and install the dependencies in the Brewfile. Run from a clean main matching GitHub main; the pinned engine, lobby, helper checkouts must be clean at their pinned commits, including engine submodules. The script uses your existing local engine/Mesa/compiler caches, so unchanged native code is not rebuilt. The GitHub Actions build workflow remains available for optional use.

No version, build number, release title, or key input is needed. The script:

  1. Checks the existing GitHub CLI login and verifies the production signing key.
  2. Chooses the next YYYYMM.DD.PATCH using the Toronto date and all GitHub releases and tags, including drafts. Chooses a Sparkle build number above every existing release/draft appcast.
  3. Builds and audits the app, then runs the settings, updater and release checks.
  4. Creates the styled DMG without Finder automation prompts, signs the DMG and appcast, and mounts the image read-only to audit the actual packaged app.
  5. Uploads only the DMG, SHA-256 checksum and signed appcast.xml to an unpublished draft. Diagnostic/source metadata stays local. The release title is only the version number, such as 202610.29.0.
  6. Opens that draft's edit page in your browser. Edit the description and click Publish release when ready; publish as a stable release marked Latest to update the Sparkle channel and trigger the Homebrew cask workflow.

By default the signing backup is read from ~/.config/zkmacos/sparkle-private-key; its public half must match GitHub's SPARKLE_PUBLIC_ED_KEY repository variable. The script never generates a new key. Use --private-key-file /secure/path or SPARKLE_PRIVATE_KEY_FILE to select another backup. Existing SPARKLE_PRIVATE_ED_KEY and SPARKLE_PUBLIC_ED_KEY environment variables are also supported. Private keys are never passed in command-line arguments, written to build logs or uploaded with the artifacts.

To supply your own Markdown before editing the draft:

./scripts/create-release.py --iterm --notes-file /path/to/release-notes.md

Other useful options:

./scripts/create-release.py --iterm --check         # Preflight only; no build/upload
./scripts/create-release.py --iterm --prepare-only  # Signed local artifacts; no draft
./scripts/create-release.py --no-open               # Print the draft editor URL
./scripts/build-app.sh --iterm                      # App build only

Omit --iterm to run in the current terminal. Both commands show named stages, elapsed time, and progress bars using Rich. A separate Engine compilation bar uses Ninja's completed/total task counts and percentage; compiler messages do not advance that bar. A long compile/link task leaves the count unchanged until it finishes. Cached builds report that no compilation is needed. Steps without measurable progress show a spinner instead of an invented percentage. --verbose shows full tool output, and --plain disables animations. CI and redirected output automatically use plain logging. Logs and completion status are saved under build/logs/ (build.log, release.log, and the corresponding *-result.json files). A checkout lock prevents simultaneous pipelines from replacing one another's outputs. Failed commands stop the pipeline and retain the logs and local artifacts for inspection.

The script never publishes automatically. GPU playtesting, multiplayer synchronization and installation testing on another supported Mac remain manual release validation. These builds use ad-hoc signing without a developer certificate or notarization.

Failures and retries

Preflight checks GitHub CLI authentication, clean/pushed main, clean pinned forks/submodules, and the private/public signing-key pair before building. Fix the reported problem and rerun. Do not change the engine’s reported version or rotate the production key to bypass a failure.

Build and release logs are under build/logs/, including release.log and release-result.json. A failed step stops later steps. Local artifacts remain for inspection; do not publish a partial draft. If GitHub creation/upload failed after creating a draft, inspect it before retrying; the next automatic version allocation includes drafts and will not reuse that draft’s version.

--prepare-only runs the full local build/check/package/sign/mounted-DMG audit without uploading. Normal runs upload only Zero-K-macOS-arm64.dmg, Zero-K-macOS-arm64.dmg.sha256, and the signed appcast.xml. Sparkle uses the DMG and appcast; the checksum supports manual verification and Homebrew publication. The JSON source/dependency/audit reports remain local in dist/ and the build logs. release-build.json records the source commit, version and build number. Never modify a signed DMG/feed afterward without regenerating signatures.

Signing configuration

Sparkle uses its own Ed25519 signing key, independently of Apple Developer ID. Existing ZkMacOS releases already use a production key. Restore that key or export its existing Keychain entry; do not generate a replacement to fix a missing local backup. The following generation command is only for the first signing setup of a new distribution:

.cache/sparkle-2.10.1/bin/generate_keys --account zkmacos

In this GitHub repository's Settings → Secrets and variables → Actions, set:

  • Repository variable SPARKLE_PUBLIC_ED_KEY to the public key printed by the tool. Local update-enabled builds need the same environment variable.
  • Repository secret SPARKLE_PRIVATE_ED_KEY to the contents exported by generate_keys --account zkmacos -x /path/to/private-key-file. Export outside the checkout, upload it as a secret, then remove the temporary export.

Keep a secure backup of this key. Without Developer ID signing, losing the private key prevents authenticating future updates for existing installations. Do not generate a new key for each release. No private key belongs in Git or release assets. CI fails before building if either setting is missing and checks that the signing key matches the public key embedded in the app before publishing. This does not provide Apple signing or notarization; initial macOS approval still applies.

Optional GitHub Actions build

Open Actions → Build and publish macOS release → Run workflow, select main, and click Run workflow after configuring the signing configuration. No version input is needed. The workflow builds the pinned sources on an Apple Silicon macOS 26 runner, runs the settings checks and app audit, creates the styled DMG without Finder automation, and publishes a GitHub release with the DMG, SHA256 checksum, signed appcast.xml. Source/dependency/audit metadata is retained in the workflow artifacts. It then calls the Homebrew cask workflow to update the tap.

CalVer is automatic: YYYYMM.DD.PATCH uses the date in America/Toronto when the run starts. The first release of a day uses .0; later releases increment the highest matching patch found across all releases and tags. Failed builds do not consume a version. Release runs are serialized, and an existing release is never replaced. The selected version is embedded in the app; the workflow run number supplies its build number.

The workflow caches Homebrew downloads, checksum-verified source archives, Python and NuGet packages, compiled Mesa libraries, and C/C++ compiler results. Mesa and compiler caches account for native toolchain changes. App packaging, auditing, and DMG creation run fresh. Build logs are uploaded even on failure. The first run has cold caches and takes longer.

CI checks do not replace GPU playtesting, multiplayer synchronization testing, or installation testing on another Mac. Review the workflow logs and keep the known limitations in release notes current.

Homebrew publication

The Update Homebrew cask workflow downloads the published DMG and checksum, verifies them, generates Casks/zkmacos.rb with an exact versioned URL and SHA256, and commits it to main. This repository doubles as the tap, so a separate homebrew-* repository or cross-repository token is not required. The cask requires Apple Silicon and macOS 26+, installs Zero-K.app, and leaves Application Support data untouched during upgrades and uninstallations.

The automatic release workflow invokes this workflow directly because a release published using GitHub's built-in Actions token does not trigger a second workflow through the release event.

Drafts and prereleases do not update the cask. An older release cannot downgrade it, and a changed binary under an existing version is rejected: publish a new version instead. If publishing happened before both assets were attached, upload the missing assets and run Actions → Update Homebrew cask → Run workflow, supplying the release tag. You can also prepare the cask locally with an authenticated GitHub CLI:

uv run --python python3 scripts/update-cask.py --tag 202610.27.0

GitHub Actions needs permission to write repository contents and push the cask commit to main. If branch rules prevent that push, commit the generated cask through your normal review process instead. The cask becomes available to players after its commit reaches main and their tap is refreshed.

The inputs are version-pinned; byte-for-byte identical DMGs are not currently claimed. See distribution details for the trust process and packaging constraints.

Release-only reporting

The release pipeline sets ZKMACOS_RELEASE_BUILD=1, compiling Sentry reporting into that release build. Ordinary scripts/build-app.sh builds omit it and cannot upload Sentry events or attachments, regardless of saved telemetry settings. Build metadata records build_kind. Do not opt local development builds into the release flag.

Clone this wiki locally