From 466fef3c233ccde7eb3fec0dddc47e9affe6f843 Mon Sep 17 00:00:00 2001 From: Olivier Date: Thu, 24 Sep 2026 20:10:12 -0400 Subject: [PATCH] docs: add RELEASING.md with the full release/update checklist --- README.md | 2 + RELEASING.md | 177 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 RELEASING.md diff --git a/README.md b/README.md index 309b016..649b86a 100644 --- a/README.md +++ b/README.md @@ -250,6 +250,8 @@ onyx --version ## Development +See [RELEASING.md](RELEASING.md) for the full version-bump/build/tag/release checklist. + ### Running Tests ```bash diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..454c721 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,177 @@ +# 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 ..."`. + +## 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 + +`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/ +``` + +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 + +```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.