Skip to main content

Release And Versioning

Use this guide for the current Holon production release contract.

Current Release Contract​

  • Holon uses one shared semver across the Rust runtime workspace, the Tauri desktop shell, the HolonClient renderer package, the docs website package, lockfiles, and the top docs/system/changelog.md entry.
  • Supported release tags are vX.Y.Z, vX.Y.Z-alpha.N, vX.Y.Z-beta.N, and vX.Y.Z-rc.N.
  • The local contributor loop stays npm --prefix ./Frontend/HolonDesktop run dev:light. Production releases are separate tagged GitHub Releases builds.
  • Packaged desktop builds surface in-app updates through channel manifests, not raw commit history.
  • Holon currently supports two in-app update channels: stable and preview.
  • The first supported production target is Windows x64 only.

Distribution Shape​

Tagged releases publish through GitHub Releases.

Channel manifests publish through GitHub Releases assets:

  • stable.json on the latest stable release
  • preview.json on the rolling preview prerelease

The current Windows release lane produces:

  • holon-desktop-<version>-windows-x64-setup.exe
  • holon-desktop-<version>-windows-x64-setup.exe.sig
  • stable.json
  • holon-<version>-windows-x64.zip
  • holon-<version>-sha256.txt

The preview lane produces:

  • holon-desktop-preview-<version>-windows-x64-setup.exe
  • holon-desktop-preview-<version>-windows-x64-setup.exe.sig
  • preview.json
  • holon-preview-sha256.txt

For Windows desktop users:

  • Download and run holon-desktop-<version>-windows-x64-setup.exe.
  • holon-desktop-<version>-windows-x64-setup.exe.sig is updater metadata used by Holon release verification and in-app updates. It is not something users run directly.
  • holon-<version>-windows-x64.zip is the CLI archive containing holon.exe. It is not the desktop app.
  • Preview users should normally switch channels inside Holon instead of manually downloading every preview installer.
  • The in-app install flow is restart-oriented: after a successful install, Holon Desktop restarts immediately to load the updated binary.

The desktop updater uses Tauri's updater plugin with channel-specific GitHub Releases static endpoints:

stable:  https://github.com/<owner>/<repo>/releases/latest/download/stable.json
preview: https://github.com/<owner>/<repo>/releases/download/preview/preview.json

Channel Rules​

  • stable is the default production lane and is published only from tagged releases.
  • preview is a rolling prerelease lane published from the latest successful default-branch CI run or manual preview dispatch.
  • The app persists the selected channel in machine-local app_config.json under the existing desktop app config surface.
  • Preview desktop packages use a CI-only Tauri app version like X.Y.Z-preview.<date>.<run>+sha.<short> so Tauri's updater can distinguish newer preview builds without changing the repo-wide source-of-truth version files.
  • Stable builds continue to use the shared repo semver X.Y.Z / prerelease tag version.
  • A stable install may opt into preview when the selected preview build shares the same base X.Y.Z; after that, normal semver ordering handles newer preview builds.

Version Source Of Truth​

runtime/Cargo.toml [workspace.package.version] is the primary source of truth.

Release validation then requires matching versions in:

  • Frontend/HolonDesktop/src-tauri/Cargo.toml
  • Frontend/HolonDesktop/src-tauri/tauri.conf.json
  • Frontend/HolonDesktop/package.json
  • Frontend/HolonDesktop/package-lock.json
  • Frontend/HolonClient/package.json
  • Frontend/HolonClient/package-lock.json
  • docs/website/package.json
  • docs/website/package-lock.json
  • runtime/Cargo.lock
  • Frontend/HolonDesktop/src-tauri/Cargo.lock
  • docs/system/changelog.md

pwsh -File ./scripts/verify-version.ps1 is the authoritative parity check for this contract.

Local Release Preparation​

From the repo root:

pwsh -File ./scripts/bump-version.ps1 0.1.0-rc.1
pwsh -File ./scripts/verify-version.ps1 -Tag v0.1.0-rc.1
npm --prefix ./Frontend/HolonDesktop run package:stage:win-x64
npm --prefix ./Frontend/HolonDesktop run verify:packaging-readiness

Recommended validation before pushing a release tag:

cargo test --manifest-path ./runtime/Cargo.toml
npm --prefix ./Frontend/HolonClient run lint
npm --prefix ./Frontend/HolonClient run typecheck
npm --prefix ./Frontend/HolonClient run test -- --run
npm --prefix ./Frontend/HolonDesktop run test
pwsh -File ./scripts/check-doc-authoring.ps1
pwsh -File ./scripts/check-doc-links.ps1

GitHub Release Flow​

  • Push a matching v<version> tag to trigger .github/workflows/release.yml.
  • Release tags must already exist and resolve to a commit reachable from origin/master.
  • Manual dispatch uses the same tag contract: provide an existing release tag, and the workflow checks out that tag before building. publish_release=false is a signed release dry run that uploads workflow artifacts but does not publish a GitHub Release.
  • The workflow verifies version parity and packaging readiness before building.
  • The workflow smoke-tests the packaged Windows installer in silent mode and fails the release if installation, app startup, runtime database initialization, or Authenticode validation fails.
  • The desktop release config is generated in CI so updater keys, channel endpoints, preview endpoint knowledge, and Windows signing settings stay out of committed repo files.
  • The stable workflow creates or reuses a draft GitHub Release, uploads desktop and CLI assets, verifies the GitHub release asset contract, checks that stable.json targets the canonical installer asset, publishes checksums that match the uploaded asset names, then publishes the release.

Preview Release Flow​

  • Pushes to master trigger .github/workflows/preview-release.yml directly.
  • Preview release publication now updates on each master commit; it is no longer gated on a separate workflow_run CI completion trigger.
  • The preview workflow publishes to the rolling GitHub prerelease tag preview.
  • Preview assets are intentionally desktop-only for now; the CLI archive remains part of the stable tagged release contract.
  • The preview workflow generates a CI-only Tauri config version override and publishes preview.json so in-app preview updates compare correctly.
  • The preview workflow now publishes holon-preview-sha256.txt and verifies both preview manifest targeting (preview.json) and preview checksums after upload.

Non-Goals​

  • No Microsoft Store distribution.
  • No macOS or Linux production release lane yet.
  • No separate version numbers for desktop and CLI.
  • No network runtime, sidecar, or subprocess packaging path.