Skip to content

RELEASING.md

Latest commit

 

History

History
99 lines (63 loc) · 2.91 KB

RELEASING.md

File metadata and controls

99 lines (63 loc) · 2.91 KB

Releasing Voxclip

This document is for maintainers and release engineers.

Source-of-truth files

  • Release workflow: .github/workflows/release.yml
  • CI validation workflow: .github/workflows/ci.yml
  • GoReleaser config: .goreleaser.yml
  • Changelog and release notes: CHANGELOG.md
  • Whisper staging details: packaging/whisper/README.md
  • User-facing CLI docs: README.md

Release-related commands

Use these commands to validate release setup locally:

task whisper:build
task release:check
task release:dry

Equivalent GoReleaser commands:

goreleaser check
goreleaser release --snapshot --clean

Changelog policy

CHANGELOG.md is user-facing release notes.

  • Keep entries focused on CLI behavior, flags, workflows, installation UX, and compatibility notes.
  • Do not list internal-only refactors, CI plumbing, or dependency bumps unless users are affected.
  • Keep upcoming changes under ## [Unreleased] and move them into a dated version section when tagging a release.

Bundled whisper binaries

Before packaging, platform-specific whisper binaries must be staged under packaging/whisper/....

For exact expected paths and host-local staging instructions, see packaging/whisper/README.md.

Release archives include the staged binary as:

libexec/whisper/whisper-cli

Release archives also include licensing docs:

LICENSE
THIRD_PARTY_NOTICES.md

Pre-tag checklist

Before tagging a release:

  1. Update Version in internal/version/version.go to match the upcoming tag (without the v prefix).
  2. Move CHANGELOG.md entries from [Unreleased] into a dated version section.

The release workflow verifies that the hardcoded version matches the git tag and will fail early if they diverge.

GitHub Actions release flow

.github/workflows/release.yml runs on version tags (v*) and manual dispatch.

The workflow builds and stages whisper-cli for:

  • linux/amd64
  • linux/arm64
  • darwin/amd64
  • darwin/arm64

It then runs GoReleaser to publish release archives and checksums.txt.

Release delivery is via GitHub Releases assets (not GitHub Packages):

  • voxclip_<version>_<os>_<arch>.tar.gz
  • checksums.txt

Each per-platform archive bundles both executables (voxclip and libexec/whisper/whisper-cli), so end-user installs do not compile whisper.cpp locally.

Homebrew cask publishing

Releases automatically update the Homebrew cask in fmueller/homebrew-tap via GoReleaser's homebrew_casks: stanza.

Required secret

Add a GitHub secret named HOMEBREW_TAP_TOKEN to the fmueller/voxclip repository:

  1. Create a fine-grained PAT at GitHub Settings > Developer Settings > Fine-grained tokens.
  2. Scope it to fmueller/homebrew-tap with Contents: Read and write permission.
  3. Add it as a repository secret in Settings > Secrets and variables > Actions.

Prerelease tags (containing a hyphen) skip the cask update (skip_upload: auto).