Docs ยท releases

Versioning and releases

Spooktacular follows Semantic Versioning 2.0.0: every release is major.minor.patch, so a version number tells you what an upgrade can and cannot break. Predictable releases for enterprise stability.

What each number means

The three positions carry three different promises, exactly as defined by semver.org.

Major

Breaking changes

Breaking changes to CLI commands, API endpoints, or the SpooktacularKit public API. Requires migration steps.

Minor

New features

New features, new commands, new API endpoints. Fully backward-compatible. Safe to upgrade.

Patch

Fixes

Bug fixes, performance improvements, documentation updates. Always safe to upgrade immediately.

Pre-1.0 stability Spooktacular is currently pre-1.0, so minor versions may include breaking changes; every breaking change is documented in the release notes. During the 0.x series, treat minor version bumps as potentially breaking and pin to a specific version in production environments.

What counts as the public API

Semver guarantees apply to named surfaces. Everything else may change in any release.

The following surfaces are covered by semver stability guarantees (post-1.0):

  • CLI commands: Command names, flags, and output format for machine-parseable output
  • HTTP API: Endpoint paths, request/response schemas, status codes
  • SpooktacularKit: Public types, methods, and protocols
  • VM bundle format: On-disk structure of .spookvm bundles
  • LaunchDaemon plist format: Service configuration schema

The following are not covered by stability guarantees:

  • Internal types (anything not marked public)
  • GUI layout and visual design
  • Human-readable CLI output formatting
  • File paths for internal caches

Pinning versions

For enterprise deployments, pin to a specific version so upgrades happen on your schedule, not the project's.

build from source, pinned
# pin to a specific tag or commit
$ git clone https://github.com/Spooky-Labs/spooktacular.git
$ cd spooktacular
$ git checkout <tag-or-commit>
$ ./build-app.sh release
Swift Package Manager
// pin to an exact version
.package(url: "https://github.com/Spooky-Labs/spooktacular", exact: "0.1.0")

// or use a range
.package(url: "https://github.com/Spooky-Labs/spooktacular", from: "0.1.0")

Signed releases, a Homebrew cask and GitHub Release downloads: aren't published yet, so build from source pinned to a tag or commit instead.

macOS compatibility

The requirement that matters most: macOS guests need a macOS 27 host, because the shared base image is built with DiskImageKit.

SpooktacularmacOSNotes
0.1.x macOS 27 (host) Required for macOS guests. The shared base image is built with DiskImageKit
0.1.x macOS 27+ (guest) Required for native guest provisioning (VZMacGuestProvisioningOptions) on --github-runner creates; older guests boot to a normal, manually-completed Setup Assistant
0.1.x macOS 26+ (host) Liquid Glass support (optional)

Release process and support

Best-effort community support from an open-source project, with the process written down.

Release process

  • Tags: Every release is tagged as v{MAJOR}.{MINOR}.{PATCH} in Git
  • GitHub Releases: Every tag gets a GitHub Release with release notes; signed binaries will be attached there once binary releases begin
  • Changelog: Breaking changes are documented in release notes with migration instructions
  • Tests: Every release must pass the full suite, 865 tests in 222 suites

Support policy

  • Latest release: Actively maintained with bug fixes and security patches
  • Previous minor: Critical security fixes only
  • Older releases: No active support; upgrade recommended

Enterprise teams needing guaranteed SLAs should consider contributing to the project or sponsoring development via GitHub Discussions.