release-sidecar

name	release-sidecar
description	Release new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release.
disable-model-invocation	true

Releasing a New Version

Prerequisites

• Go installed matching go.mod version
• Clean working tree (git status shows no changes)
• All tests passing (go test ./...)
• GitHub CLI authenticated (gh auth status)
• No replace directives in go.mod
• GoReleaser configured (.goreleaser.yml in repo root)
• HOMEBREW_TAP_TOKEN secret exists in GitHub repo settings

Beware of go.work: A parent go.work file can silently use local dependencies instead of published versions. Always use GOWORK=off when updating dependencies and testing builds.

Release Process

1. Determine Version

Follow semantic versioning:

• Major (v2.0.0): Breaking changes
• Minor (v0.2.0): New features, backward compatible
• Patch (v0.1.1): Bug fixes only

git tag -l | sort -V | tail -1

2. Update td Dependency

Sidecar embeds td as a Go module. Always update to latest before releasing:

GOWORK=off go get github.com/marcus/td@latest
GOWORK=off go mod tidy

3. Verify go.mod

Ensure no replace directives (they break go install):

grep replace go.mod && echo "ERROR: Remove replace directives before releasing!" && exit 1

4. Verify Build Without go.work

GOWORK=off go build ./...

If this fails with "undefined" errors, the required dependency version hasn't been published yet.

5. Update CHANGELOG.md

## [vX.Y.Z] - YYYY-MM-DD

### Features
- New feature description

### Bug Fixes
- Fix description

### Dependencies
- Dependency update description

git add CHANGELOG.md
git commit -m "docs: Update changelog for vX.Y.Z"

6. Create and Push Tag

git tag vX.Y.Z -m "Brief description of release"
git push origin main && git push origin vX.Y.Z

7. GitHub Release + Homebrew Tap (Both Automated)

Pushing the tag triggers .github/workflows/release.yml, which has two jobs:

1. goreleaser — creates the GitHub Release, builds/attaches binaries for darwin/linux (amd64/arm64), and generates checksums.txt. The GitHub release notes are auto-generated by GoReleaser from commit subjects (excluding docs:/test:/ci:/chore:) — these are separate from the hand-written CHANGELOG.md, which is bundled into the archives.
2. update-homebrew-tap — runs after goreleaser, computes the source tarball's sha256, and rewrites the tag URL + sha256 in Formula/sidecar.rb in marcus/homebrew-tap, then commits and pushes.

GoReleaser-the-tool does not publish the formula (there is no brews: block, because the formula builds from source to dodge macOS Gatekeeper warnings). The bump is done by the update-homebrew-tap job, not by GoReleaser. Earlier versions of this skill said the tap had to be bumped by hand — that is no longer true for sidecar.rb.

7b. Manual Homebrew Steps (only when needed)

For a normal sidecar-only release you do nothing here — the update-homebrew-tap job bumps Formula/sidecar.rb for you. The job is a no-op if the formula is already current (it checks git diff --cached --quiet).

You only touch the tap by hand in two cases:

• The job failed (e.g. token/permission error). Re-run the update-homebrew-tap job from the Actions UI, or bump it manually:

  curl -sL "https://github.com/marcus/sidecar/archive/refs/tags/vX.Y.Z.tar.gz" | shasum -a 256
  cd /opt/homebrew/Library/Taps/marcus/homebrew-tap   # or clone marcus/homebrew-tap
  # Edit Formula/sidecar.rb — update the URL tag and sha256
  git add Formula/sidecar.rb && git commit -m "sidecar: bump to vX.Y.Z" && git push
  

• Co-releasing td and/or nightshift. The job only touches sidecar.rb. If this release also bumps the td dependency (step 2) or nightshift, update Formula/td.rb / Formula/nightshift.rb by hand the same way.

8. Verify

# Check workflow succeeded
gh run list --workflow=release.yml --limit=1

# Check release exists with binaries
gh release view vX.Y.Z

# Test Homebrew install
brew install marcus/tap/sidecar
sidecar --version

# Test go install (critical!)
GOWORK=off go install github.com/marcus/sidecar/cmd/sidecar@vX.Y.Z
sidecar --version
# Should output: sidecar version vX.Y.Z

# Test update notification
go build -ldflags "-X main.Version=v0.0.1" -o /tmp/sidecar-test ./cmd/sidecar
/tmp/sidecar-test
# Should show toast: "Update vX.Y.Z available!"

Version in Binaries

Version is embedded at build time via ldflags:

go build -ldflags "-X main.Version=v0.2.0" ./cmd/sidecar
go install -ldflags "-X main.Version=v0.2.0" ./cmd/sidecar

Without ldflags, version falls back to:

1. Go module version (if installed via go install)
2. Git revision (devel+abc123)
3. devel

Update Mechanism

On startup, sidecar checks https://api.github.com/repos/marcus/sidecar/releases/latest, compares tag_name against current version, and shows a toast if newer. Results cached for 3 hours. Pre-release suffixes (-rc1, -beta) are stripped for comparison. Dev versions skip the check.

Recovery: Fixing a Bad Release

1. Publish a new patch release with fixes
2. For critical bugs, release immediately
3. Delete unpublished GitHub release: gh release delete vX.Y.Z
4. Keep git tags to preserve history
5. If GoReleaser workflow fails, re-run locally: goreleaser release --clean

Install Methods

1. Setup script: curl -fsSL https://raw.githubusercontent.com/marcus/sidecar/main/setup.sh | bash
2. Homebrew: brew install marcus/tap/sidecar
3. Download binary: from GitHub Releases page
4. From source: go install github.com/marcus/sidecar/cmd/sidecar@latest

Checklist

• Tests pass
• Working tree clean
• td dependency updated (GOWORK=off go get github.com/marcus/td@latest)
• No replace directives in go.mod
• Build works without go.work (GOWORK=off go build ./...)
• CHANGELOG.md updated
• Version follows semver
• Tag created and pushed
• GitHub Actions workflow completed
• Binaries attached to release
• update-homebrew-tap job green and Formula/sidecar.rb bumped (automatic; manual only if it failed — see step 7b)
• td/nightshift formulas bumped by hand IF co-releasing them (step 7b)
• Installation verified (GOWORK=off go install ...@vX.Y.Z)
• Update notification verified