Skip to content

Release process

This document describes the manual steps a maintainer runs to cut a new ithyno release. The workflow is deliberately narrow: local reproducible builds plus a git tag whose push automatically drives the 3-OS CI build and creates a GitHub Release with all installer assets attached. Signing, notarization, and marketplace publication are out of scope for this workflow — see Out of scope below.

Maintainer sequence

  1. Bump the version across all three owned package.json files (package.json, electron/package.json, vscode-extension/package.json; vscode-extension/host/package.json is a generated build artifact regenerated by prepack.mjs and is NOT bumped here):
npm run release:version -- <next-version>
# Example: npm run release:version -- 0.0.2-alpha.0

The script validates the argument with semver.valid() and exits non-zero if the value is not valid semver 2.0.0. No files are modified on failure.

  1. Update CHANGELOG.md: add a ## [<next-version>] - YYYY-MM-DD section summarising the changes in this release.

  2. Run the release build:

npm run release:build

This runs, in order: - npm run typecheck - npm test - npm run build (web) - npm run --workspace ithyno-electron build (TypeScript compile of the Electron shell) - npm run --workspace ithyno-vscode package → vscode-extension/ithyno-<version>.vsix - npm run --workspace ithyno-electron package:<platform> → electron/dist/ithyno-<version>-<arch>.<ext> - node scripts/verify-bundle.mjs — bundle-shape + init-from-bundle byte-compare against templates/.claude/ - node scripts/release-summary.mjs — prints a summary of produced artifacts (path + size)

Fails fast if any step exits non-zero. Because the summary runs after verify-bundle, a verify-bundle failure short-circuits before the summary is printed. For iterating on verification without paying the full chain's cost, run npm run release:verify-bundle on its own.

  1. Smoke-test each produced artifact:
  2. Install and launch the Electron app from its installer (DMG/NSIS/AppImage).
  3. Install the VSIX in VS Code (Extensions: Install from VSIX…) and open the dashboard.

  4. Confirm the displayed version matches the release.

  5. Create a git tag:

git tag v<version>
git push origin v<version>

Pushing the v<version> tag automatically triggers .github/workflows/release.yml, which:

  • verifies package.json.version matches the stripped tag (fails loudly if not);
  • runs release:build in parallel on macOS, Windows, and Linux;
  • runs a publish job (gated on refs/tags/*) that uses softprops/action-gh-release@v2 with permissions: contents: write to create a GitHub Release keyed by the tag and attach .vsix, .dmg, .exe, and .AppImage assets.

Branch pushes (including main) do not trigger the workflow — the tag push is the single authoritative build, so the same commit is never built twice.

Out of scope

The following are not handled by this workflow and are tracked as follow-ups:

Topic Notes
Code signing (macOS / Windows) Requires Apple Developer / EV certificates and secure secret storage.
Notarization (macOS) Requires an Apple ID with notarization entitlements and Xcode tools.
VS Code Marketplace publish Requires a VSCE_PAT personal access token from the publisher account.
npm registry publish Requires an npm access token and a decision on the package scope.
Auto-update wiring Requires a signed update manifest and a distribution server (e.g. S3, GitHub Releases).

When these follow-ups are implemented, update this document to reflect the new steps and move the corresponding items out of the "Out of scope" table.