179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
# 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/<file>
|
|
```
|
|
|
|
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.
|