Files
onyx-cli/RELEASING.md
T

5.4 KiB

Release procedure

Onyx ships as two standalone binaries (Windows .exe, Linux ELF) attached to a Gitea release — no PyPI package, no installer. This document is the checklist for cutting a new version.

1. Land the change

Implement, then verify:

python -m pytest tests/ -q

All tests must pass (skips are fine) before bumping anything.

2. Bump the version

The version string lives in exactly one place: the @click.version_option decorator on the cli group in src/onyx.py.

@click.version_option(version='X.Y.Z', prog_name='onyx')

Use semver: patch for fixes only, minor for new commands/flags, major for breaking changes (removed/renamed commands, changed config schema).

3. Build both platform binaries

PyInstaller does not cross-compile — each binary must be built natively on its target platform.

Windows (run directly on this machine):

rm -rf build dist
python -m PyInstaller onyx.spec
# -> dist/onyx.exe

Linux (via WSL, since this machine is Windows): build on WSL's native ext4 filesystem, not /mnt/c/... — PyInstaller/venvs are unreliable over the drvfs 9p mount.

wsl -d Ubuntu-24.04 -- bash -lc '
  set -e
  rm -rf ~/onyx-build && mkdir -p ~/onyx-build
  cp -r "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/src" ~/onyx-build/
  cp "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/onyx.spec" ~/onyx-build/
  cp "/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/requirements.txt" ~/onyx-build/
  cd ~/onyx-build
  python3 -m venv .venv
  .venv/bin/pip install -q --upgrade pip
  .venv/bin/pip install -q -r requirements.txt pyinstaller
  rm -rf build dist
  .venv/bin/pyinstaller onyx.spec
'

Copy the result out and rename it (Windows already produced dist/onyx.exe in the same folder, and Linux's output has no extension — rename to avoid any ambiguity):

wsl -d Ubuntu-24.04 -- bash -lc "cp /home/oli/onyx-build/dist/onyx '/mnt/c/Users/oli/Documents/o/Resources/repos/Onyx - obsidian cli tool/dist/onyx-linux'"

Passing multi-line scripts to wsl.exe through a shell tool can mangle line endings (CRLF) and silently break variable assignments. If a WSL command behaves inexplicably (e.g. command not found for something that should be a variable), write the script to a file and run that file instead of an inline heredoc.

4. Verify both binaries

dist/onyx.exe --version          # Windows, via cmd.exe (see gotcha below)
wsl -d Ubuntu-24.04 -- ~/onyx-build/dist/onyx --version

Confirm the printed version matches step 2. Smoke-test at least one command end to end (e.g. periodic --view, weekly --date 2025-11-27) against a scratch vault/config — never against the real ~/.onyx-cli/config.yaml.

Windows gotcha: the plain bash tool can't execute a freshly built .exe directly (command not found) — always invoke it through cmd.exe /c "onyx.exe ...".

5. Deploy locally (optional)

Copy the Windows build to the installed location so onyx on this machine picks up the new version immediately:

cp dist/onyx.exe "/c/Users/oli/Documents/o/Resources/app back up/bin/onyx.exe"

6. Commit, tag, push

git add -A
git commit -m "chore: bump to vX.Y.Z"

git fetch origin        # someone may have committed via the Gitea web UI
git log --oneline origin/main -3

If origin/main has commits you don't have locally, rebase, don't merge (this repo's history is linear):

git rebase origin/main

Then tag (annotated, with a real changelog since the last tag) and push:

git tag -a vX.Y.Z -m "vX.Y.Z

- ..."
git push origin main
git push origin vX.Y.Z

If you rebased after creating the tag, the tag still points at the pre-rebase (now orphaned) commit. Delete and recreate it: git tag -d vX.Y.Z && git tag -a vX.Y.Z -m "..." before pushing.

7. Create the Gitea release

tea hangs indefinitely under a plain non-interactive shell call, for any subcommand, including fully local ones. Always launch it as a supervised process (hub start/wait/logs), never via the bash tool directly.

Write release notes to a scratch file, then create the release with both assets in one call:

tea releases create --repo olivier/onyx-cli --tag vX.Y.Z --title vX.Y.Z \
  --note-file release-notes-vX.Y.Z.md -a dist/onyx.exe -a dist/onyx-linux

If the release already exists and you're adding a platform binary later (e.g. the Linux build wasn't ready yet), attach it separately instead:

tea releases assets create --repo olivier/onyx-cli vX.Y.Z dist/<file>

Delete the scratch release-notes file afterward — it's not a repo convention file.

tea repos create --owner olivier fails with GetOrgByName — --owner targets an organization, not your personal account. Omit it entirely when creating a repo under your own user.

8. Verify the release

curl -s https://gitea.mithrilforge.dev/api/v1/repos/olivier/onyx-cli/releases/tags/vX.Y.Z \
  | python -c "import json,sys; d=json.load(sys.stdin); [print(a['name'], a['size']) for a in d['assets']]"

Confirm both onyx.exe and onyx-linux are listed with nonzero, distinct sizes.

9. Clean up

wsl -d Ubuntu-24.04 -- bash -lc "rm -rf ~/onyx-build"
rm -f release-notes-vX.Y.Z.md

dist/ and build/ are gitignored — the binaries never get committed, only attached to the release.