fusion/RELEASING.md

Releasing

This project uses changesets for automated versioning and release management. Releases are distributed through two channels:

1. npm packages — published automatically via version.yml using changesets
2. GitHub Release with platform binaries — built and uploaded via release.yml when a version tag is pushed

How it works

1. Add a changeset

When you make a change that should be included in a release, add a changeset:

pnpm changeset

This will prompt you to:

• Select which packages are affected
• Choose the semver bump type (patch, minor, major)
• Write a summary of the change

Then edit the created changeset file to use the structured body format:

---
"@runfusion/fusion": minor
---

summary: Add a Command Center productivity control for LOC backfills.
category: feature
dev: Uses the new `fn_backfill_loc` tool; settings key `commandCenter.locBackfill`.

Fields:

• summary (required) — one line, user-facing, max 120 chars.
• category (required) — one of: feature, fix, breaking, security, performance, internal.
• dev (optional) — developer/migration detail.

A markdown file will be created in the .changeset/ directory. Commit this file along with your code changes. Validate with pnpm check:changesets.

2. Version PR is created automatically

When changesets are merged to main, the version.yml workflow automatically opens (or updates) a "Version Packages" pull request. This PR:

• Consumes all pending changeset files
• Bumps package versions according to the changeset declarations
• Generates/updates CHANGELOG.md files for affected packages
• Distills the version's changeset summaries into grouped, end-user-facing release notes in the root CHANGELOG.md

3. Merge the Version PR to release

When you merge the Version Packages PR:

• The version.yml workflow detects that all changesets have been consumed
• It builds all packages and publishes them to npm with provenance attestation
• It creates a git tag v{version} based on the kb CLI package version
• The tag push triggers release.yml, which:
  • Builds platform-specific binaries for Linux x64, macOS x64, macOS arm64, and Windows x64
  • Builds the Android APK as fusion-android.apk
  • Signs macOS binaries (codesign + notarization) and Windows binaries (Authenticode)
  • Generates SHA256 checksums for all binaries and the Android APK
  • Creates a GitHub Release with all binaries, the Android APK, and checksums attached

Release channels

Channel	Workflow	Trigger	Output
npm	version.yml	Push to main	npm packages with provenance
GitHub Release	release.yml	Version tag (v*)	Signed platform binaries, Android APK + checksums

Platform binaries

Platform	Binary name	Signed
Linux x64	fusion-linux-x64	—
macOS arm64	fusion-darwin-arm64	✓ (codesign + notarization)
Windows x64	fusion-windows-x64.exe	✓ (Authenticode)
Android	fusion-android.apk	— (debug/unsigned APK)

macOS Intel (darwin-x64) is intentionally not shipped: the CLI is Apple-Silicon-only because macos-13 GitHub runners are too scarce to build reliably. The desktop macOS DMG/ZIP remains universal.

Testing binary builds

Use the Test Release workflow (test-release.yml) to manually test binary builds without creating a real release:

1. Go to Actions → Test Release → Run workflow
2. The workflow builds all 4 platform binaries plus the Android APK, runs smoke tests, and uploads artifacts
3. Download the all-binaries artifact to inspect the output

Manual release (fallback)

If you need to release manually, you can still push a version tag directly:

git tag v0.2.0
git push origin v0.2.0

This will trigger release.yml to build binaries and create a GitHub Release. Note: npm publishing is handled separately by version.yml and won't be triggered by a manual tag push.

Available scripts

Script	Description
pnpm changeset	Add a new changeset
pnpm changeset status	Check pending changesets
pnpm release	Local interactive release: previews changesets, lets you accept or override the proposed version, then bumps + builds + publishes + tags
pnpm release --yes	Same, but auto-accepts the proposed version and skips the final confirmation
pnpm release --dry-run	Preview only — show changesets, proposed version, and prompt for override, then exit before any file/git/npm changes
pnpm release:version	Apply changesets and bump versions (used by CI)
pnpm --filter @runfusion/fusion build:exe	Build binary for current platform
pnpm --filter @runfusion/fusion build:exe -- --target <target>	Cross-compile for a specific platform
pnpm --filter @runfusion/fusion build:exe:all	Build binaries for all platforms

Tips

• Every user-facing change should have a changeset — CI will remind you if one is missing
• You can add multiple changesets per PR if you're making changes to multiple packages
• Changeset files are automatically deleted when versions are bumped
• CI verifies binary compilation on every push/PR to catch build regressions early
• If your project enables completionDocumentationMode: "changeset", triage specs will explicitly require .changeset/*.md completion artifacts for relevant tasks; keep this aligned with your repo's release convention.

Internal packages

The following packages are internal and are not published to npm:

• @fusion/core — Core domain model and task store
• @fusion/dashboard — Web UI and API server
• @fusion/engine — AI agents and orchestration
• @fusion/plugin-sdk — Plugin development SDK
• @fusion-plugin-examples/* — Example plugins

These packages have private: true in their package.json and are listed in the .changeset/config.json ignore array to prevent accidental publishing. Only the @runfusion/fusion package is published to npm.