A release is an annotated semver tag on main plus a GitHub Release,
with binaries attached. The update check announces releases (it reads
/repos/bricef/htt/releases/latest), and go install …@latest
resolves to the newest tag, so both matter; the binaries are for
people without Go.
Releases are made by hand, when you decide to, with just recipes
that run scripts/release.sh. You need gh signed in to GitHub and
an up-to-date checkout of main. Publishing the release starts a
GitHub Actions workflow that builds the binaries (see
Binaries).
-
Pick the version. Semver. While htt is
v0.x, a release that adds features or removes one bumps the minor version, and a fixes-only release bumps the patch. -
Check
main:just release-check vX.Y.ZThis changes nothing. It stops at the first check that fails:
- the version is
vX.Y.Z, not yet tagged, and newer than the last release; - the working tree is clean and
HEADisorigin/main; - CI passed for that commit;
just test,just vet,just check,go mod tidy -diffand govulncheck (the version CI runs) pass locally.
It ends by listing what was merged since the last release, to write the notes from. Fix anything govulncheck says htt's code reaches before releasing; a standard-library fix means raising the
godirective ingo.mod(see Go versions). - the version is
-
Write the notes in a Markdown file outside the repo: what's new, how to install (
go install github.com/bricef/htt/cmd/htt@vX.Y.Z, or download a binary, as the README's Installation section says), and where the known issues are (TODO.md). The recipe refuses notes that don't mention the version. -
Release:
just release vX.Y.Z /path/to/notes.mdIt runs every check again, then:
- tags the commit (
git tag -a vX.Y.Z <commit> -m "htt vX.Y.Z") and pushes the tag; - publishes the GitHub Release (
gh release create … --verify-tag --latest): not a draft and not a pre-release, since/releases/latestskips both and the update check wouldn't see it; - verifies it as a user would, from a temporary directory outside
the repo:
go install …@vX.Y.Z,htt --version,go list -m …@latest(retrying for a few minutes while the module proxy catches up), and GitHub's latest release; - waits for the release-binaries run for the tag (up to 3 minutes
for it to start and 30 to finish), then checks the release: every
archive and the checksums file are attached, and the archive for
this machine matches the checksums, has an attestation from the
workflow (
gh attestation verify), and holds anhttwhose--versionishtt version vX.Y.Z.
If a step fails after the tag is pushed, the recipe prints the command that finishes the release; don't start again (see below). For the binaries that's
just release-binaries vX.Y.Z, once whatever failed is fixed.RELEASE_DRY_RUN=1 just release …prints the tag and publish commands instead of running them, and lists the files the binaries run would attach. - tags the commit (
-
Check the update notice if you like: an older build run at a terminal should now print it.
release-binaries.yml
runs when a release is published. It builds, for Linux and macOS on
amd64 and arm64:
htt_vX.Y.Z_<os>_<arch>.tar.gz, holdinghtt,README.mdandLICENSE(releases before the MIT licence was added, v0.3.0 and earlier, have noLICENSE);htt_vX.Y.Z_SHA256SUMS, the SHA-256 of each archive;
then makes a signed build-provenance attestation for the archives and uploads them all to the release, replacing any of the same name. The build and the upload are separate jobs, so the build, which compiles third-party code, holds no token that can write to the repository or sign attestations.
The build is scripts/dist.sh, and just dist vX.Y.Z runs it locally, into dist/. It builds the tagged commit,
whatever is checked out, from a fresh clone of the tag
(CGO_ENABLED=0, -trimpath, stripped). The version matters:
htt --version prints the one Go stamped into the binary, and the
update check is off in a build without one. Go stamps the tag's
version only when the build runs in a clean git checkout with the tag
at HEAD, which the clone is. The script checks every binary's build
info (go version -m: the version, platform, CGO_ENABLED=0,
-trimpath, no local modifications), runs the one for the machine it
runs on, and fails if anything is off.
just release-binaries vX.Y.Z runs the workflow again for a release
that's already published (gh workflow run release-binaries.yml -f tag=vX.Y.Z, from main), waits for that run, and makes the same
checks as just release. Use it when a release's binaries failed, or
to give an older release binaries. The workflow has to be on main
for this to work.
There's no Windows build: htt doesn't build for Windows, because
goterm v1.0.3 uses unix.EOPNOTSUPP on every platform (goterm
v1.0.4 fixes it). Once htt builds there, adding windows/amd64 and
windows/arm64 to the platforms in scripts/dist.sh is all it takes;
their archives are zips.
The Go module proxy caches every version it has served, forever. Never
move, delete or reuse a tag; if a release is wrong, fix forward with a
new patch release. A GitHub Release's notes can be edited afterwards
(gh release edit vX.Y.Z --notes-file notes.md).
go install pkg@version builds with the user's own Go, switching to a
newer toolchain only when the module's go directive asks for one. It
ignores the toolchain line, which only applies to builds inside a
checkout. So to make every build use a patched standard library, raise
the go directive (go get go@1.26.N); with the default
GOTOOLCHAIN=auto, an older local Go downloads that version for the
build. v0.1.0 learned this the hard way: it pinned the toolchain line
only, and go install built it with whatever Go the user had.