Builds, packaging, and version policy

The repository remains at 0.2.0-dev. Packaging tools produce local archives; no stable release or Marketplace extension has been published by this work.

Use a binary archive

Choose the archive matching the machine: Windows, Linux, or macOS (darwin), and x86-64 (amd64) or ARM64 (arm64). Windows uses ZIP; Linux/macOS use tar.gz. Extract into an empty directory. The executable, license, guides, examples, branding, editor syntax files, and BUILD.json are included. Go is not required to run the executable.

From the extracted directory on Windows:

.\zy.exe --version
.\zy.exe check --json examples/modules/main.zy
.\zy.exe examples/modules/main.zy

On Linux/macOS:

./zy --version
./zy check --json examples/modules/main.zy
./zy examples/modules/main.zy

Verify the archive against SHA256SUMS before extraction. On Windows use Get-FileHash -Algorithm SHA256 <archive> and compare the listed digest. On Linux use sha256sum -c SHA256SUMS; on macOS use shasum -a 256 -c SHA256SUMS when all listed archives are present. Checksums detect differing bytes; these artifacts are not code-signed or notarized.

Build locally

Requirements: Git, Go 1.22 or later, and Python 3.11 or later. Release CI pins Go 1.26.0; use that version when comparing its outputs. Node.js/npm is needed for installing the optional VS Code language-client dependencies and for editor development tests. Those dependencies are not bundled in the archives; see language-server setup.

From a clean checkout:

python tools/release.py --version 0.2.0-dev

The default output is a new dist/0.2.0-dev/ directory containing six platform archives and SHA256SUMS. Existing output directories are refused to prevent mixing artifacts. Select platforms or another new destination:

python tools/release.py --version 0.2.0-dev --target windows/amd64 --output dist/windows-review

For reviewing uncommitted development work, explicitly add --allow-dirty with a prerelease version. BUILD.json records the dirty flag and base revision; that revision alone cannot reproduce uncommitted changes. This option is never accepted for a stable build. Failed builds retain partial output for inspection and do not write a final checksum manifest. Choose a new directory when retrying.

The builder passes argument lists directly to Go, disables CGO, workspace/ambient Go flags and automatic toolchain switching, removes filesystem paths with -trimpath, disables implicit VCS embedding, and sets main.version through the linker. These flags follow the Go command documentation. Each archive records version, revision, dirty state, target, and Go version in BUILD.json.

Archives use sorted paths, fixed timestamps/modes, and normalized ownership. Reproducibility requires identical source bytes, compiler, Python/compression implementation, build environment, and options; it is not a promise of identical output across different toolchains or line-ending conversions. The tests compare archive bytes across reordered inputs. Native binary/archive rebuild comparison is part of local release validation.

Verification

go test ./... -count=1 -timeout=60s
go vet ./...
python -m unittest discover -s tools -p 'test_*.py'
python tools/smoke_release.py dist/0.2.0-dev/zy-0.2.0-dev-windows-amd64.zip

Use a host-compatible archive for the last command. The smoke test verifies its checksum, extracts into a temporary directory, runs the packaged binary, checks version/JSON diagnostics/modules/formatting, runs success/failure fixtures for all three workflows, and exercises stdio diagnostics, formatting, hover, completion, and definition with unsaved text and UTF-16 positions. The binary is invoked directly with an empty PATH; Go and checkout-relative examples are not used during the smoke test.

CI runs Go tests and native archive smoke tests on Windows, Linux, and macOS for both amd64 and arm64. Go 1.22 remains in the compatibility matrix on the original three runners; stable Go covers all six native targets. Linux/stable also runs the race detector. Ubuntu/amd64 runs real VS Code extension-host integration in a virtual display.

The manual Build release artifacts workflow builds all six archives once, uploads them as a temporary artifact, then downloads and executes each cross-built archive on its matching native host. Each native job verifies GOHOSTOS/GOHOSTARCH before running the binary. It does not create a GitHub release or push a tag. See the Actions runs for results; configured jobs are not evidence of a successful run.

Version and release gates

• 0.x versions are experimental. Behavior changes need migration notes; minor versions may contain breaking changes, while patch versions should preserve documented behavior except bug fixes.
• Prereleases use lowercase identifiers, for example 0.2.0-dev or 0.2.0-rc.1. Archive/CLI versions omit v; Git tags use v0.2.0.
• Stable packaging requires a clean checkout with the exact matching tag at HEAD. The script checks this but never creates the tag. Source builds retain the development default unless the linker supplies a version.
• Keep release notes, migration documentation, and version labels consistent. Preserve diagnostic schema/code meanings according to the diagnostic contract.
• Before publishing, require native CI and clean-install results for supported targets, review the bundled license/docs, confirm checksums, and record the relevant user-trial results. Any unsupported or failed native target must be stated in release notes.
• Do not call a package production-ready solely because it builds. Signing/notarization, public distribution, and a supported embedding API require separate decisions.

See implementation progress for what was actually validated in this workspace.