release

Release — Orbit Agents Release Process

Execution Process

Step 1: Confirm Version Number

Read the current version number in package.json , and ask the user for the new version number to release (default is patch +1).

Update the version number in the following two places:

package.json the version field of
src/renderer/src/App.tsx the version number display text in the bottom-left corner

Step 2: Commit Version Number Changes

git add package.json src/renderer/src/App.tsx
git commit -m "chore: bump version to <VERSION>"

Step 3：Build

⚠️ You must use npm run build:mac / npm run build:win, do not directly call npx electron-builder

build:mac will use rebuild:native to force-recompile better-sqlite3 into arm64 before packaging. Directly running electron-builder will skip this step, and the cross-platform shared node_modules native binary may be of the wrong architecture (for example, an x64 binary left over from a Windows build just completed), and the built mac App will silently fail to open a window. This is issue #3

# macOS（會自動 rebuild:native → arm64，再打包）
npm run build:mac

# Windows（electron-builder 打包時會自動抓 better-sqlite3 的 Windows 預編版）
npm run build:win

Wait for the build to complete, and confirm that the following are generated under dist/ :

macOS: Orbit-Agents-<VERSION>-arm64.dmg, Orbit-Agents-<VERSION>-arm64.zip
Windows: Orbit-Agents-Setup-<VERSION>.exe, Orbit-Agents-<VERSION>-x64-win.zip

After packaging, be sure to verify the architecture of the mac native binary to avoid issue #3 recurring:

file "dist/mac-arm64/Orbit Agents.app/Contents/Resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node"
# 預期輸出要包含：Mach-O 64-bit bundle arm64

Step 4: Generate Update Files

4a. asar lightweight update package (gzip compressed)

Use the dedicated script to generate the compressed asar:

bun run prepare-asar

This will automatically generate:

dist/app-asar-v<VERSION>.gz — gzip-compressed asar update package

4b. latest-mac.yml

Calculate the sha512 (base64 encoded) of the zip and dmg, and generate the YAML:

ZIP_SHA512=$(shasum -a 512 dist/Orbit-Agents-<VERSION>-arm64.zip | awk '{print $1}' | xxd -r -p | base64)
ZIP_SIZE=$(stat -f%z dist/Orbit-Agents-<VERSION>-arm64.zip)
DMG_SHA512=$(shasum -a 512 dist/Orbit-Agents-<VERSION>-arm64.dmg | awk '{print $1}' | xxd -r -p | base64)
DMG_SIZE=$(stat -f%z dist/Orbit-Agents-<VERSION>-arm64.dmg)
RELEASE_DATE=$(date -u "+%Y-%m-%dT%H:%M:%S.000Z")

Format:

version: <VERSION>
files:
  - url: Orbit-Agents-<VERSION>-arm64.zip
    sha512: <ZIP_SHA512>
    size: <ZIP_SIZE>
  - url: Orbit-Agents-<VERSION>-arm64.dmg
    sha512: <DMG_SHA512>
    size: <DMG_SIZE>
path: Orbit-Agents-<VERSION>-arm64.zip
sha512: <ZIP_SHA512>
releaseDate: '<RELEASE_DATE>'

4c. latest.yml (Windows)

Calculate the sha512 (base64 encoded) of the exe, and generate the YAML:

EXE_SHA512=$(shasum -a 512 dist/Orbit-Agents-Setup-<VERSION>.exe | awk '{print $1}' | xxd -r -p | base64)
EXE_SIZE=$(stat -f%z dist/Orbit-Agents-Setup-<VERSION>.exe)
RELEASE_DATE=$(date -u "+%Y-%m-%dT%H:%M:%S.000Z")

Format:

version: <VERSION>
files:
  - url: Orbit-Agents-Setup-<VERSION>.exe
    sha512: <EXE_SHA512>
    size: <EXE_SIZE>
path: Orbit-Agents-Setup-<VERSION>.exe
sha512: <EXE_SHA512>
releaseDate: '<RELEASE_DATE>'

Step 5: Push and Create GitHub Release

git push origin main

Create the release and upload all files (7 in total):

gh release create v<VERSION> \
  dist/Orbit-Agents-<VERSION>-arm64.dmg \
  dist/Orbit-Agents-<VERSION>-arm64.zip \
  dist/Orbit-Agents-<VERSION>-x64-win.zip \
  dist/Orbit-Agents-Setup-<VERSION>.exe \
  dist/app-asar-v<VERSION>.gz \
  dist/latest-mac.yml \
  dist/latest.yml \
  --title "v<VERSION>" \
  --notes "<RELEASE_NOTES>"

Step 6: Write Release Notes

Release notes use English, format reference:

## What's New

### Feature Category Name
- Description of change 1
- Description of change 2

### Another Category
- Description of change

Writing principles:

Summarize changes from the commit history between the last release tag and now
Use git log <PREV_TAG>..HEAD --oneline to get the commit list
Categorize by feature (such as UI, Fixes, Performance, etc.)
Each description should be concise and clear, explaining what was changed and why
There is no need to list trivial commits such as chore/version number changes

Step 7: Completion Confirmation

Output:

Release URL
List and sizes of uploaded files (there should be 7 files in total)

Release File List

Each release should include the following 7 files:

File	Purpose
`Orbit-Agents-<VERSION>-arm64.dmg`	macOS installer
`Orbit-Agents-<VERSION>-arm64.zip`	macOS zip
`Orbit-Agents-<VERSION>-x64-win.zip`	Windows zip
`Orbit-Agents-Setup-<VERSION>.exe`	Windows installer
`app-asar-v<VERSION>.gz`	gzip-compressed lightweight update package
`latest-mac.yml`	macOS auto-updater information
`latest.yml`	Windows auto-updater information