Merge pull request #36 from andreagrandi/add-install-smoke-tests

Add install smoke tests and release verification docs

Author: andreagrandi

.gitignore

@@ -33,3 +33,6 @@ go.work.sum
 
 # Sentire
 sentire
+
+# GoReleaser snapshot output
+dist/

.opencode/agent/new-release.md

@@ -4,12 +4,18 @@ mode: subagent
 ---
 
 When asked to create a new release, you need to:
-- Make sure `make test` passes without errors
+- Make sure `make test` passes without errors (this also runs the
+  `go install` smoke test via `TestGoInstallSmoke`)
+- If `goreleaser` is installed locally, also run `make smoke-release` to
+  verify the release artifacts build and the unpacked binary works
 - Use the provided version number or
   Bump the version number in internal/version/version.go:
   if you find `const Version = "0.1.0"` change to `const Version = "0.1.1"`
 - Update the changelog writing a short summary of the changes since last release (with bullet points), follow existing format
 - git commit the changes you just did
 - git push the changes you just did
 - do `git tag v<version>` (use the version you just bumped to in the `internal/version/version.go`)
-- do `git push origin v<version>`
+- do `git push origin v<version>`
+- After the GitHub `Release` workflow finishes, run the post-release
+  verification checklist in `docs/releases.md` (GitHub artifact, `go install`,
+  and Homebrew)

CHANGELOG.md

@@ -12,6 +12,7 @@ All notable changes to Sentire will be documented in this file.
 - Contributor and agent guidance for keeping `CHANGELOG.md` updated, plus a PR template prompting for an `[Unreleased]` entry
 - `docs/workflows.md` with recipe-style triage, inspection, and reporting workflows plus a troubleshooting checklist for auth, permissions, filters, and empty results
 - `Ctrl+C` (SIGINT) and SIGTERM cancel in-flight API requests, reported with a `canceled` error code
+- `docs/releases.md` with the release pipeline overview and a post-release verification checklist for `go install`, GitHub artifacts, and the Homebrew tap
 
 ### Changed
 - Request timeouts surface a clear `timeout` error code instead of a generic transport failure
@@ -27,6 +28,7 @@ All notable changes to Sentire will be documented in this file.
 - Lower `go.mod` minimum to Go 1.24 and add Go 1.24/1.25 to the CI build matrix
 - API requests use context-aware HTTP request creation, propagating cancellation and deadlines from CLI commands into the client
 - Add `make vet` target and CI step running `go vet ./...`
+- Add install smoke tests: `TestGoInstallSmoke` (runs by default) verifies the public `go install` path, and `make smoke-release` runs an opt-in goreleaser snapshot smoke test against the unpacked archive
 
 ## [0.3.0] - 2026-03-07
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test clean install help vet
+.PHONY: build test clean install help vet smoke-install smoke-release
 
 # Default target
 all: build
@@ -63,6 +63,16 @@ install: build
 	@echo "Installing sentire..."
 	@cp sentire $(GOPATH)/bin/
 
+# Run the `go install` smoke test (mirrors the public install path)
+smoke-install:
+	@echo "Running go install smoke test..."
+	@go test ./tests/ -run TestGoInstallSmoke -v -count=1
+
+# Run the goreleaser snapshot smoke test (requires goreleaser locally)
+smoke-release:
+	@echo "Running release artifact smoke test..."
+	@SENTIRE_SMOKE_RELEASE=1 go test ./tests/ -run TestGoreleaserSnapshotSmoke -v -count=1 -timeout 10m
+
 # Cross-compile for multiple platforms
 build-all:
 	@echo "Building for multiple platforms..."
@@ -85,4 +95,6 @@ help:
 	@echo "  vet           - Run go vet static analysis"
 	@echo "  lint          - Lint code (requires golangci-lint)"
 	@echo "  install       - Install binary to GOPATH/bin"
+	@echo "  smoke-install - Run go install smoke test against the local module"
+	@echo "  smoke-release - Build a goreleaser snapshot and smoke-test the archive (requires goreleaser)"
 	@echo "  help          - Show this help message"

README.md

@@ -388,6 +388,12 @@ To bypass the hook temporarily (not recommended):
 git commit --no-verify
 ```
 
+## Releases
+
+See [`docs/releases.md`](docs/releases.md) for the release pipeline overview
+and the post-release verification checklist for `go install`, the GitHub
+release artifacts, and the Homebrew tap.
+
 ## Changelog
 
 User-visible changes are tracked in [`CHANGELOG.md`](CHANGELOG.md). When you

docs/releases.md

@@ -0,0 +1,101 @@
+# Releasing Sentire
+
+This guide covers the steps to cut a new release and the verification you
+should perform on each public install path before announcing the version.
+
+The release pipeline itself is automated: pushing a tag matching `v*` to
+GitHub triggers the `Release` workflow, which runs the test suite and then
+invokes [GoReleaser](https://goreleaser.com) (see `.goreleaser.yaml`) to
+build cross-platform archives, publish them to the GitHub release page, and
+update the [Homebrew tap](https://github.com/andreagrandi/homebrew-tap).
+
+For the version-bump and tagging workflow itself, see
+`.opencode/agent/new-release.md`.
+
+## Pre-release smoke tests
+
+Before tagging, run the local smoke tests. Neither requires Sentry
+credentials.
+
+```bash
+# Verifies the public `go install` path against the local module.
+make smoke-install
+
+# Builds a full goreleaser snapshot, extracts the current OS/arch archive,
+# and runs `sentire version` and `sentire --help` against the unpacked
+# binary. Requires goreleaser to be installed locally (`brew install
+# goreleaser`).
+make smoke-release
+```
+
+`make smoke-install` runs as part of normal development (it is included in
+`make test` via `TestGoInstallSmoke`). `make smoke-release` is opt-in
+because a full snapshot build cross-compiles for every supported platform
+and adds noticeable time; it is also skipped automatically when goreleaser
+is not on PATH, so it does not break CI environments that lack it.
+
+## Post-release verification
+
+After the `Release` workflow finishes, verify each advertised install path
+end to end. Replace `<version>` with the tag you just pushed (without the
+leading `v` for `go install` queries; with it for the GitHub release page).
+
+### 1. GitHub release artifacts
+
+1. Open the release page:
+   <https://github.com/andreagrandi/sentire/releases/tag/v\<version\>>
+2. Confirm archives for `Darwin_x86_64`, `Darwin_arm64`, `Linux_x86_64`,
+   `Linux_arm64`, and `Windows_x86_64` are attached, along with
+   `checksums.txt`.
+3. Download the archive for your platform, extract it, and run:
+
+   ```bash
+   ./sentire version    # should print "sentire version <version>"
+   ./sentire --help     # should print top-level usage
+   ```
+
+### 2. `go install`
+
+In a clean shell (no `SENTRY_API_TOKEN` set), run:
+
+```bash
+GOBIN="$(mktemp -d)"
+export GOBIN
+go install github.com/andreagrandi/sentire/cmd/sentire@v<version>
+"$GOBIN/sentire" version    # should report v<version>
+"$GOBIN/sentire" --help
+```
+
+If `go install @latest` should also resolve to the new tag, run the same
+check with `@latest`.
+
+### 3. Homebrew
+
+The release workflow pushes an updated formula to
+`andreagrandi/homebrew-tap`. After the workflow finishes, verify the tap
+end to end:
+
+```bash
+brew update
+brew install andreagrandi/tap/sentire   # or `brew upgrade ...` if installed
+sentire version    # should report the new version
+sentire --help
+```
+
+If the formula has not yet been updated, the workflow log under
+`Release → goreleaser` will show the push to the tap repository — check
+both this repo's Actions tab and the tap repo's commit history.
+
+## Troubleshooting
+
+- **`go install` returns an older version.** Module proxies cache versions;
+  `GOPROXY=direct go install github.com/andreagrandi/sentire/cmd/sentire@v<version>`
+  forces a fresh fetch from GitHub.
+- **`brew install` reports "no such formula".** The tap may not be tapped
+  yet. Run `brew tap andreagrandi/tap` first, or use the fully qualified
+  formula name `andreagrandi/tap/sentire`.
+- **`sentire version` reports `unknown` or a stale version.** The release
+  archives are built with ldflags that inject the version
+  (`internal/version.Version`). If the value is wrong, the goreleaser
+  config drifted — check `.goreleaser.yaml` and the most recent commit on
+  the tag.