Keep prereleases out of stable package channels

.github/workflows/release.yml

@@ -126,7 +126,8 @@ jobs:
     environment: release
     permissions:
       contents: read
-    if: startsWith(github.ref, 'refs/tags/v')
+    # Only publish the normal AUR package for stable tags. Prereleases stay on GitHub Releases.
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:

.goreleaser.yaml

@@ -73,9 +73,16 @@ notarize:
 changelog:
   use: github-native
 
+release:
+  prerelease: auto
+  # Keep prerelease tags out of GitHub's latest release/install-script path.
+  make_latest: "{{ if .Prerelease }}false{{ else }}true{{ end }}"
+
 homebrew_casks:
   - name: fizzy
     ids: [default]
+    # Do not update the normal tap for prerelease tags.
+    skip_upload: auto
     repository:
       owner: basecamp
       name: homebrew-tap
@@ -92,6 +99,8 @@ homebrew_casks:
 scoops:
   - name: fizzy
     ids: [default]
+    # Do not update the normal bucket manifest for prerelease tags.
+    skip_upload: auto
     repository:
       owner: basecamp
       name: homebrew-tap

RELEASING.md

@@ -23,7 +23,31 @@ Pushing the tag triggers the GitHub Actions release workflow, which:
 
 ## Versioning
 
-Follow [semver](https://semver.org/). Use `v` prefix for tags: `v4.0.0`, `v4.1.0-rc.1`.
+Follow [semver](https://semver.org/). Use `v` prefix for tags: `v4.0.0`, `v4.0.0-beta1`, `v4.1.0-rc.1`.
+
+Stable tags like `v4.0.0` publish to all normal distribution channels. Prerelease tags with a suffix like `-beta1`, `-beta.1`, or `-rc.1` are marked as GitHub prereleases and are not marked as the latest GitHub release.
+
+## Beta / Prerelease Releases
+
+Use a prerelease tag when technical testers need a build before the next stable version:
+
+```bash
+make release VERSION=v4.0.0-beta1
+```
+
+Prerelease behavior is intentionally conservative so existing package-manager users do not upgrade unless they explicitly opt in. Example behavior:
+
+| Surface | Stable tag `v4.0.0` | Prerelease tag `v4.0.0-beta1` |
+|---------|----------------------|--------------------------------|
+| GitHub Releases | Published as a normal release and eligible to be GitHub's latest release. | Published as a GitHub prerelease and explicitly not marked latest. |
+| Release assets | Binaries, archives, checksums, SBOMs, `.deb`, and `.rpm` artifacts are uploaded. | Same artifacts are uploaded for explicit tester download/install. |
+| curl installer | Installs `v4.0.0` once GitHub marks it latest. | Does not install the prerelease via `releases/latest`; testers must download assets explicitly. |
+| Homebrew | Updates the normal `basecamp/tap/fizzy` cask. `brew upgrade fizzy` can move users to `v4.0.0`. | Does not update the normal cask (`skip_upload: auto`). Existing `brew upgrade fizzy` users stay on the latest stable cask. |
+| Scoop | Updates the normal `fizzy` manifest. `scoop update fizzy` can move users to `v4.0.0`. | Does not update the normal manifest (`skip_upload: auto`). Existing Scoop users stay on the latest stable manifest. |
+| AUR | Updates the normal `fizzy-cli` package if `AUR_KEY` is configured. | Skips the AUR publish job. Existing AUR users stay on the latest stable package. |
+| Go install | The git tag exists for users who explicitly request it. | The prerelease tag exists for users who explicitly request it; no package-manager manifest is updated. |
+
+Technical testers can install prereleases explicitly from the GitHub release assets, for example by downloading the asset for their OS/architecture from `https://github.com/basecamp/fizzy-cli/releases/tag/v4.0.0-beta1`.
 
 ## CI Secrets
 
@@ -50,9 +74,9 @@ Follow [semver](https://semver.org/). Use `v` prefix for tags: `v4.0.0`, `v4.1.0
 | Channel | Location | Updated by |
 |---------|----------|------------|
 | GitHub Releases | `basecamp/fizzy-cli/releases` | GoReleaser |
-| Homebrew | `basecamp/homebrew-tap` Casks/fizzy.rb | GoReleaser |
-| Scoop | `basecamp/homebrew-tap` fizzy.json | GoReleaser |
-| AUR | `aur.archlinux.org/packages/fizzy-cli` | `publish-aur.sh` |
+| Homebrew | `basecamp/homebrew-tap` Casks/fizzy.rb | GoReleaser (stable tags only) |
+| Scoop | `basecamp/homebrew-tap` fizzy.json | GoReleaser (stable tags only) |
+| AUR | `aur.archlinux.org/packages/fizzy-cli` | `publish-aur.sh` (stable tags only) |
 | Go install | `go install github.com/basecamp/fizzy-cli/cmd/fizzy@latest` | Go module proxy |
 | curl installer | `scripts/install.sh` | Manual |