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.exethrough a shell tool can mangle line endings (CRLF) and silently break variable assignments. If a WSL command behaves inexplicably (e.g.command not foundfor 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
.exedirectly (command not found) — always invoke it throughcmd.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 pointingHOMEat 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.