logan
b3a0814f24
CLAUDE.md said .releaserc.yml was a config nothing ran and that there were five workflows; both stop being true with this branch. The CI section now names release.yml as the entry point and records the four things in it that are load-bearing, including the two silent failure modes worth pinning against. packaging/homebrew/README.md and docs/android-release.md say where a user would actually look that upgrading from 1.x needs a reinstall -- Homebrew offers nothing silently, and Android refuses outright.
95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# YellowJacket Homebrew formula
|
|
|
|
The formula builds YellowJacket from source on macOS and Linuxbrew, mirroring
|
|
the Arch `PKGBUILD`: the Wails toolchain resolves from `go.mod`'s tool
|
|
directives and drives the frontend build itself, so the only build inputs are
|
|
Go, Node, and pnpm.
|
|
|
|
```
|
|
packaging/homebrew/
|
|
└── Formula/
|
|
└── yellowjacket.rb ← canonical source; CI syncs it to the tap repo
|
|
```
|
|
|
|
## Installing
|
|
|
|
```bash
|
|
brew install shadow-puppet/yellowjacket/yellowjacket
|
|
```
|
|
|
|
`shadow-puppet/yellowjacket` is Homebrew shorthand for the tap repo
|
|
`github.com/Shadow-Puppet/homebrew-yellowjacket`. Brew auto-taps it, so there's
|
|
no separate `brew tap` step. To build the tip of `main` instead of the latest
|
|
release, add `--HEAD`.
|
|
|
|
### Upgrading from 1.x needs a reinstall, once
|
|
|
|
Releases became automatic and restarted at **0.0.1** (plan 017), which is
|
|
*lower* than the `1.3.0` this tap last published. Homebrew compares versions
|
|
and has no equivalent of pacman's `epoch`, so `brew upgrade` sees a downgrade
|
|
and offers **nothing at all** — silently, which is indistinguishable from the
|
|
tap having gone stale.
|
|
|
|
```bash
|
|
brew uninstall yellowjacket && brew install shadow-puppet/yellowjacket/yellowjacket
|
|
```
|
|
|
|
Nothing is stored inside the Cellar, so this costs a rebuild and no data. It is
|
|
a one-time step: 0.0.2 onwards upgrade normally.
|
|
|
|
## How publishing works
|
|
|
|
This directory holds the **canonical** formula. The tap users install from lives
|
|
in a **separate** repo — `homebrew-yellowjacket` — because Homebrew only
|
|
discovers formulae from a repo whose name starts with `homebrew-`, with the
|
|
formula at a top-level `Formula/`. Keeping it separate is also why nothing has
|
|
to live in this repo's root.
|
|
|
|
On every version tag (`v*`), `.gitea/workflows/homebrew-formula.yml`:
|
|
|
|
1. downloads the GitHub release tarball for that tag,
|
|
2. computes its `sha256`,
|
|
3. rewrites the `version` and `sha256` lines in the formula, and
|
|
4. commits the result to `homebrew-yellowjacket`'s `Formula/yellowjacket.rb`.
|
|
|
|
So a normal release needs **no manual formula edits** — tag, and the tap updates
|
|
itself. (This is the Homebrew equivalent of the Arch package's publish workflow.)
|
|
|
|
### About the `sha256`
|
|
|
|
Homebrew re-downloads the source tarball on each install and refuses to build
|
|
unless its checksum matches `sha256` — integrity/tamper detection. The committed
|
|
value here is a `REPLACE_WITH_...` placeholder on purpose; the real checksum is
|
|
computed and injected by CI at release time, so it never has to be maintained by
|
|
hand. (The Arch `PKGBUILD` sidesteps this with `SKIP` because it clones over git
|
|
rather than downloading a tarball.)
|
|
|
|
## One-time setup
|
|
|
|
1. **Create the tap repo:** `Shadow-Puppet/homebrew-yellowjacket` on GitHub,
|
|
with a `main` branch. It can start empty — the first tagged release seeds
|
|
`Formula/yellowjacket.rb`.
|
|
2. **Add a CI secret:** `HOMEBREW_TAP_TOKEN` — a GitHub token with write access
|
|
to that repo (a fine-grained PAT scoped to `homebrew-yellowjacket`, Contents:
|
|
read/write, is enough).
|
|
|
|
That's it. The source repo must be public (or the tap private with an
|
|
authenticated `brew install`) for brew to fetch the release tarball.
|
|
|
|
## Notes
|
|
|
|
- **License**: declared as `license :cannot_represent` (custom license). Replace
|
|
with the correct SPDX identifier once the license is finalized.
|
|
- **macOS vs Linux**: under Wails v3 the bundling is a separate step from the
|
|
build. `wails3 task build` produces a bare `yellowjacket` binary in `bin/` on
|
|
both platforms; on macOS the formula runs `wails3 task package` instead, which
|
|
wraps that binary in a `yellowjacket.app` (installed under the Cellar with an
|
|
`exec` shim in `bin`).
|
|
- **Linuxbrew**: building on Linux additionally needs the system WebKitGTK/GTK
|
|
stack (`webkitgtk-6.0`, `gtk4`, `alsa-lib`) — OS packages, not Homebrew deps.
|
|
v2's `webkit2gtk-4.1`/`gtk3` is now only the `-tags gtk3` escape hatch. macOS
|
|
needs only the Xcode Command Line Tools.
|
|
- **Cask alternative**: if you later ship prebuilt macOS `.dmg`/`.zip` artifacts,
|
|
a Homebrew *cask* pointing at those installs faster than this source build.
|
|
This formula is the source-build path.
|