docs: add release runbook
- commit
- e5b4925a3634a57ccda011fabcd0572ec750a013
- author
- brice · · 2026-07-17 06:52 UTC
- parent
- bbfd790
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +41 -0
A RELEASING.md +41 -0
| @@ -0,0 +1,41 @@ | |||
| 1 | + | # Releasing vev | |
| 2 | + | ||
| 3 | + | Releases are cut by tagging: `git tag v0.X.Y && git push origin v0.X.Y`. | |
| 4 | + | The `release` workflow cross-compiles linux/amd64 + darwin/arm64 | |
| 5 | + | (`CGO_ENABLED=0`), publishes a GitHub Release with `checksums.txt`, and pushes | |
| 6 | + | the `vev-bin` PKGBUILD to AUR (stable tags only — `skip_upload: auto` skips | |
| 7 | + | AUR for `-rc.*`/`-alpha.*` prerelease tags). | |
| 8 | + | ||
| 9 | + | ## Checklist | |
| 10 | + | ||
| 11 | + | 1. main is green on both CI legs (ubuntu, macos-14). | |
| 12 | + | 2. Tag and push. Watch: `gh run watch`. | |
| 13 | + | 3. Verify the release page: two archives + `checksums.txt` + grouped changelog. | |
| 14 | + | 4. `curl -fsSL https://raw.githubusercontent.com/bnema/vev/main/install.sh | sh` | |
| 15 | + | on a Linux box; confirm `vev --version` prints the tag. | |
| 16 | + | 5. Stable tags only: confirm https://aur.archlinux.org/packages/vev-bin | |
| 17 | + | picked up the new version. | |
| 18 | + | ||
| 19 | + | ## If GitHub publishes but AUR fails | |
| 20 | + | ||
| 21 | + | Do **not** delete or re-push the tag. The GitHub release is the source of truth; | |
| 22 | + | only the PKGBUILD push failed (usually SSH/key). Fix the cause, then either: | |
| 23 | + | ||
| 24 | + | - Re-run the failed workflow job (`gh run rerun <run-id> --failed`), which | |
| 25 | + | re-executes goreleaser idempotently (`replace_existing_draft`, same tag), or | |
| 26 | + | - Push the PKGBUILD by hand: `goreleaser release --clean --skip=validate` | |
| 27 | + | locally with `AUR_KEY` exported, or clone | |
| 28 | + | `ssh://aur@aur.archlinux.org/vev-bin.git` and commit the PKGBUILD generated | |
| 29 | + | under `dist/`. | |
| 30 | + | ||
| 31 | + | ## If AUR publishes but GitHub fails | |
| 32 | + | ||
| 33 | + | Do **not** delete or re-push the tag. Fix the GitHub workflow failure and rerun | |
| 34 | + | it (`gh run rerun <run-id> --failed`); if necessary, repair the GitHub Release | |
| 35 | + | manually with the same tag's archives and `checksums.txt`, then verify both | |
| 36 | + | publication targets before proceeding. | |
| 37 | + | ||
| 38 | + | ## Version stamping | |
| 39 | + | ||
| 40 | + | `vev --version` reads `internal/app.{version,commit,date}`, stamped via | |
| 41 | + | ldflags in `.goreleaser.yaml`. Local builds report `0.1.0-dev`. | |
| @@ -0,0 +1,41 @@ | |||||
| 1 | + | # Releasing vev | |||
| 2 | + | ||||
| 3 | + | Releases are cut by tagging: `git tag v0.X.Y && git push origin v0.X.Y`. | |||
| 4 | + | The `release` workflow cross-compiles linux/amd64 + darwin/arm64 | |||
| 5 | + | (`CGO_ENABLED=0`), publishes a GitHub Release with `checksums.txt`, and pushes | |||
| 6 | + | the `vev-bin` PKGBUILD to AUR (stable tags only — `skip_upload: auto` skips | |||
| 7 | + | AUR for `-rc.*`/`-alpha.*` prerelease tags). | |||
| 8 | + | ||||
| 9 | + | ## Checklist | |||
| 10 | + | ||||
| 11 | + | 1. main is green on both CI legs (ubuntu, macos-14). | |||
| 12 | + | 2. Tag and push. Watch: `gh run watch`. | |||
| 13 | + | 3. Verify the release page: two archives + `checksums.txt` + grouped changelog. | |||
| 14 | + | 4. `curl -fsSL https://raw.githubusercontent.com/bnema/vev/main/install.sh | sh` | |||
| 15 | + | on a Linux box; confirm `vev --version` prints the tag. | |||
| 16 | + | 5. Stable tags only: confirm https://aur.archlinux.org/packages/vev-bin | |||
| 17 | + | picked up the new version. | |||
| 18 | + | ||||
| 19 | + | ## If GitHub publishes but AUR fails | |||
| 20 | + | ||||
| 21 | + | Do **not** delete or re-push the tag. The GitHub release is the source of truth; | |||
| 22 | + | only the PKGBUILD push failed (usually SSH/key). Fix the cause, then either: | |||
| 23 | + | ||||
| 24 | + | - Re-run the failed workflow job (`gh run rerun <run-id> --failed`), which | |||
| 25 | + | re-executes goreleaser idempotently (`replace_existing_draft`, same tag), or | |||
| 26 | + | - Push the PKGBUILD by hand: `goreleaser release --clean --skip=validate` | |||
| 27 | + | locally with `AUR_KEY` exported, or clone | |||
| 28 | + | `ssh://aur@aur.archlinux.org/vev-bin.git` and commit the PKGBUILD generated | |||
| 29 | + | under `dist/`. | |||
| 30 | + | ||||
| 31 | + | ## If AUR publishes but GitHub fails | |||
| 32 | + | ||||
| 33 | + | Do **not** delete or re-push the tag. Fix the GitHub workflow failure and rerun | |||
| 34 | + | it (`gh run rerun <run-id> --failed`); if necessary, repair the GitHub Release | |||
| 35 | + | manually with the same tag's archives and `checksums.txt`, then verify both | |||
| 36 | + | publication targets before proceeding. | |||
| 37 | + | ||||
| 38 | + | ## Version stamping | |||
| 39 | + | ||||
| 40 | + | `vev --version` reads `internal/app.{version,commit,date}`, stamped via | |||
| 41 | + | ldflags in `.goreleaser.yaml`. Local builds report `0.1.0-dev`. | |||