diff --git a/CHANGELOG.md b/CHANGELOG.md index cdda624..c0a2f99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 0.4.2 - Unreleased + +### Fixed +- Source-install documentation now requires Go 1.25+, matching `go.mod`. + ## 0.4.1 - 2026-07-01 ### Fixed diff --git a/README.md b/README.md index c4c79e0..bb4ceb3 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Go toolchain: ```bash go install github.com/steipete/sag/cmd/sag@latest ``` -Requires Go 1.24+. +Requires Go 1.25+. Debian/Ubuntu source build prerequisites: ```bash diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 26282e6..fced89e 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -7,27 +7,23 @@ summary: 'Release checklist for sag (GitHub release + Homebrew tap)' Follow these steps for each release. Title GitHub releases as `sag `. ## Checklist +- Start from a clean, synchronized `main` checkout and confirm the target version follows the changelog/project SemVer convention. - Update CLI version in `cmd/root.go` (`Version` field). +- Update `package.json` to the same version. - Update `CHANGELOG.md` with a section for the new version. - Run the gates: `pnpm format && pnpm lint && pnpm test && pnpm build`. -- Tag the release: `git tag -a v -m "Release "` after commits; push tags with `git push origin main --tags`. -- GitHub Actions attaches binaries (macOS universal, Linux amd64, Windows amd64) to the GitHub release automatically (workflow: `Release Binaries`). -- Update Homebrew tap formula (`../homebrew-tap/Formula/sag.rb`): - 1. Set `version ""`. - 2. Set `url "https://github.com/steipete/sag/archive/refs/tags/v.tar.gz"`. - 3. Update `sha256` from the same GitHub tag tarball: - - `curl -L -o /tmp/sag-.tar.gz https://github.com/steipete/sag/archive/refs/tags/v.tar.gz` - - `shasum -a 256 /tmp/sag-.tar.gz` - 4. Verify formula checksum matches the downloaded tarball. - 5. Ensure build step uses `system "go", "build", *std_go_args(ldflags: "-s -w"), "./cmd/sag"`. - 6. Commit and push in tap repo: `git commit -am "sag v" && git push origin main`. +- Commit the release changes, then create an annotated tag: `git tag -a v -m "Release "`. +- Push `main` and the tag. The `Release Binaries` workflow builds macOS arm64/amd64/universal, Linux arm64/amd64, and Windows amd64 archives, verifies their checksums, attaches them to the GitHub release, dispatches the Homebrew tap update, and waits for that workflow. +- Watch the exact tag workflow through completion. Repair or rerun failures before continuing. +- Verify the GitHub release: + - title is `sag ` + - body contains the complete changelog section plus links to the release commit, exact-head CI, live/behavior proof, and checksum manifest + - all expected archives, per-archive checksums, and the combined checksum manifest are attached +- Verify `steipete/homebrew-tap` updated `Formula/sag.rb` to the new release URLs and matching checksums. The release workflow owns this update; use the [Homebrew playbook](releasing-homebrew.md) for recovery. - Verify Homebrew install from tap: - `brew update && brew reinstall steipete/tap/sag` - `brew test steipete/tap/sag` - `sag --version` -- Create GitHub release for `v`: - - Title: `sag ` - - Body: bullets from `CHANGELOG.md` for that version - - Assets: optional source tarball `/tmp/sag-.tar.gz` (mention SHA256 in body) - Smoke-test CLI locally: `sag --help`, `sag voices --limit 3`, `sag -v Roger "hello"`. +- Add the next patch `Unreleased` section to `CHANGELOG.md`, commit, and push the closeout. - Announce: optional note with `brew update && brew upgrade steipete/tap/sag`. diff --git a/docs/install.md b/docs/install.md index 298425b..85a403f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -36,7 +36,7 @@ sudo install -m 0755 /tmp/sag /usr/local/bin/sag go install github.com/steipete/sag/cmd/sag@latest ``` -Requires the Go version declared in `go.mod` (1.24+). Source builds bake the Git description into the version string. +Requires the Go version declared in `go.mod` (1.25+). Source builds bake the Git description into the version string. ## From source diff --git a/docs/releasing-homebrew.md b/docs/releasing-homebrew.md index 7c16590..c973f35 100644 --- a/docs/releasing-homebrew.md +++ b/docs/releasing-homebrew.md @@ -1,66 +1,28 @@ # sag Homebrew Release Playbook -Lightweight flow to ship sag via the `steipete/tap` Homebrew tap (source build). +The `Release Binaries` workflow updates `steipete/homebrew-tap` after it uploads and verifies release assets. Do not edit the tap formula as a normal release step. -## 0) Prereqs -- macOS with Homebrew installed. -- Clean git tree on `main`. -- Go toolchain installed (Go version from `go.mod`). -- Access to tap repo sibling at `../homebrew-tap`. +## Normal flow -## 1) Verify build is green -```sh -pnpm format -pnpm lint -pnpm test -pnpm build -``` - -## 2) Bump the version in code -- Update `Version` in `cmd/root.go`. -- Update `CHANGELOG.md` entry to match. +1. Push the annotated `vX.Y.Z` tag after the release commit is on `main`. +2. Watch `Release Binaries` through its `update-homebrew-tap` job. +3. Confirm the dispatched `Update Formula` run succeeds in `steipete/homebrew-tap`. +4. Inspect `Formula/sag.rb`: its versioned artifact URLs and SHA-256 values must match the GitHub release assets and checksum manifest. +5. Sanity-check install from tap: -## 3) Tag & push ```sh -git commit -am "release: vX.Y.Z" -git tag vX.Y.Z -git push origin main --tags +brew update +brew reinstall steipete/tap/sag +brew test steipete/tap/sag +sag --version ``` -## 4) Update the Homebrew tap formula -In `../homebrew-tap/Formula/sag.rb`: +## Recovery -1. Set `version "X.Y.Z"`. -2. Set `url` to the tag source tarball: - ``` - url "https://github.com/steipete/sag/archive/refs/tags/vX.Y.Z.tar.gz" - ``` -3. Update `sha256` for that tarball: - ```sh - curl -L -o /tmp/sag.tar.gz https://github.com/steipete/sag/archive/refs/tags/vX.Y.Z.tar.gz - shasum -a 256 /tmp/sag.tar.gz - ``` -4. Ensure build step uses: - ```ruby - system "go", "build", *std_go_args(ldflags: "-s -w"), "./cmd/sag" - ``` +If the release assets exist but the tap update failed, fix the release workflow or tap workflow and rerun `Release Binaries` for the existing tag: -Commit/push in tap repo: ```sh -git commit -am "sag vX.Y.Z" -git push origin main -``` - -## 5) Sanity-check install from tap -```sh -brew uninstall sag || true -brew untap steipete/tap || true -brew tap steipete/tap -brew install steipete/tap/sag -brew test steipete/tap/sag -sag --version +gh workflow run release-binaries.yml --repo steipete/sag -f tag=vX.Y.Z ``` -## Notes -- Formula builds from source; no binary assets required. -- Keep formula minimal: version, url, sha256, license, `go` build dep, `std_go_args`. +The workflow redispatches `update-formula.yml` with the repository, tag, artifact template, and a unique request ID, then waits for the matching tap run. Verify the rerun and formula before installing. Manual formula edits are a last-resort repair and still require checksums from the exact published assets. diff --git a/docs/spec.md b/docs/spec.md index 183bf0a..d0d2a57 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -3,7 +3,7 @@ CLI that mirrors macOS `say` but uses ElevenLabs or 60db for synthesis. ElevenLabs defaults to streaming directly to speakers; 60db buffers and validates WAV output before playback. ## Runtime & deps -- Go 1.24+ +- Go 1.25+ - Playback uses built-in Go audio (MP3/WAV + oto) and should work on macOS/Linux/Windows with a default output device. - Auth via exactly one configured provider: ElevenLabs (`ELEVENLABS_API_KEY`, `SAG_API_KEY`, `--api-key`) or 60db (`SIXTYDB_API_KEY`).