Files

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 ...".

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:

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

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/<file>

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

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.