# 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: ```bash 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`. ```python @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): ```bash 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. ```bash 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): ```bash 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 ```bash 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 ..."`. > > **Linux scratch config**: run the smoke as a script file > (`wsl -d Ubuntu-24.04 -- bash smoke.sh`), and save the binary path > (`B=$HOME/onyx-build/dist/onyx`) before pointing `HOME` at a scratch > directory, so the real config stays untouched. ## 5. Deploy locally (optional) Copy the Windows build to the installed location so `onyx` on this machine picks up the new version immediately: ```bash cp dist/onyx.exe "/c/Users/oli/Documents/o/Resources/app back up/bin/onyx.exe" ``` ## 6. Commit, tag, push ```bash 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): ```bash git rebase origin/main ``` Then tag (annotated, with a real changelog since the last tag) and push: ```bash 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 Use `gt` (gitea-cli 1.0+; `tea` is archived). `gt` never pushes, so step 6 must be done first; `--verify-tag` refuses a tag the server doesn't have. From the bash tool, invoke it through `cmd.exe /c` like the exe above. Write release notes to a scratch file, then create the release with both assets in one call: ``` gt release create vX.Y.Z dist/onyx.exe dist/onyx-linux --title vX.Y.Z \ --notes-file release-notes-vX.Y.Z.md --verify-tag --no-input ``` 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 (`--clobber` replaces an asset with the same name): ``` gt release upload vX.Y.Z dist/ ``` Delete the scratch release-notes file afterward — it's not a repo convention file. ## 8. Verify the release ```bash 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 ```bash 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.