ProjectQuint/Tools/RELEASE.md

ProjectQuint macOS Alpha release harness

Public releases are always manually approved. Normal implementation, Unity tests, and Stable builds never invoke this harness and never change the public update manifest.

Machine configuration

Keep machine-specific paths out of source control. Create .release.local.json at the repository root, or set the corresponding environment variables:

JSON field	Environment variable	Purpose
deploy_host	PROJECTQUINT_DEPLOY_HOST	SSH destination
ssh_key	PROJECTQUINT_DEPLOY_KEY	Absolute path to an existing SSH identity
remote_source	PROJECTQUINT_REMOTE_SOURCE	Remote static-site source directory
stable_app	PROJECTQUINT_STABLE_APP	Absolute output path ending in .app
releases_root	PROJECTQUINT_RELEASES_ROOT	Local release artifact directory

Environment variables take precedence. Build outputs default to _workspace/builds/Stable/ProjectQuint.app and _workspace/releases. The deployment host and SSH identity are required before any remote operation. Never put private-key contents or authentication tokens in this file.

Read-only plan

Tools/release-mac-alpha.sh --revision 3

This checks the live manifest, local release source, SSH access, and required tools. It does not edit files, build, upload, or deploy.

Publish

The Stable app may remain open while the replacement build is produced. The running process is never terminated by the harness; it continues to run the previous binary until it exits.

Run:

Tools/release-mac-alpha.sh \
  --revision 3 \
  --publish \
  --title "Pack Manager and first-play improvements" \
  --change "Non-blocking first-library guidance" \
  --change "Recommended 4UE, AERY, and 6UE difficulty tables"

The harness:

1. updates the explicit release revision and build number;
2. runs the release-version and full Unity EditMode suites;
3. builds and validates the macOS Universal Stable;
4. creates, mounts, and validates a DMG with an Applications shortcut;
5. signs the DMG with the ProjectQuint Sparkle Ed25519 key stored in Keychain;
6. updates and builds the download page, changelog, JSON manifest, and appcast;
7. uploads the DMG to a new immutable OCI release directory;
8. deploys the static site only after the artifact checksum matches remotely;
9. downloads the public DMG and verifies both SHA-256 and its Sparkle signature.

If a run stops after the exact artifact has already reached OCI but before the site is switched, inspect the failure and rerun the same command with --resume. Resume accepts the remote artifact only when its checksum matches the locally verified DMG.

The previous public manifest and release remain available if any step before the final site deployment fails. Existing remote release artifacts are never overwritten.

Sparkle signing contract

• Framework: Sparkle 2.9.4
• Feed: https://projectquint.duckdns.org/updates/appcast.xml
• Keychain account: com.teamdenia.projectquint
• Public key: w94qM58k8MAhIxYYQiR1ivyR5CyMW1tlRV68lQoLehA=

The private key stays only in the macOS login Keychain. Never copy it into the project, app bundle, website, deployment server, CI variables, logs, or release reports. Backing up or moving that key is a separate, explicitly approved security operation.

The first public build that embeds Sparkle is a bridge release: users on older builds must install that DMG manually. Automatic signed replacement works from that bridge release to the following release. Because the current Alpha uses ad-hoc code signing, Gatekeeper installation instructions still apply to the bridge release; Sparkle does not replace Apple notarization.