Releasing

Pushing a v* tag runs .github/workflows/release.yml. It can also be triggered manually with an explicit tag.

Cutting a release

# 1. Bump the version in build.zig.zon
#    .version = "0.1.0"

# 2. Commit it
git commit -am "chore: version 0.1.0"

# 3. Tag and push
git tag v0.1.0
git push origin main v0.1.0

The tag drives everything else.

The version gate

The first thing the workflow does is refuse a tag that disagrees with the package:

tag="v0.1.0"
version="${tag#v}"                     # 0.1.0
declared=$(sed -n 's/.*\.version.*"\([^"]*\)".*/\1/p' build.zig.zon)

if [ "$version" != "$declared" ]; then
    echo "tag $tag implies version $version, build.zig.zon declares $declared" >&2
    exit 1
fi

The CLI prints what the package declares - build.zig reads build.zig.zon at compile time and passes the version through as a build option - so a mismatched tag would ship a binary reporting the wrong version. That cannot be fixed without a new tag, which is why it is checked before anything is built.

The full test suite runs in the same job.

Building

Six targets, in parallel, fail-fast: false:

Platform	Targets	Archive
Linux	x86_64-linux-musl, aarch64-linux-musl	.tar.gz
macOS	x86_64-macos, aarch64-macos	.tar.gz
Windows	x86_64-windows, aarch64-windows	.zip

zig build -Dtarget=$TARGET -Doptimize=ReleaseSafe -Dstrip

ReleaseSafe, not ReleaseFast. zpack parses archives it did not write, so the safety checks are worth more than the last few percent of throughput. A malformed input becomes a clean panic rather than undefined behaviour.

-Dstrip omits debug symbols. Local builds keep them.

Linux targets link musl statically, so there is no glibc version to match.

Each archive contains the binary, README.md, and LICENSE, under a directory named zpack-<version>-<target>.

Publishing

cd artifacts
sha256sum zpack-* > SHA256SUMS

gh release create "$tag" \
    --title "zpack $version" \
    --generate-notes \
    --verify-tag \
    artifacts/*

--verify-tag refuses to create a release for a tag that is not in the repository. --generate-notes builds the changelog from merged pull requests, so PR titles are the release notes - worth writing accordingly.

SHA256SUMS covers every archive, so a user can check the whole download directory at once:

sha256sum -c SHA256SUMS

Version numbering

Two independent version numbers, and confusing them causes trouble:

Version	Where	Changes when
Package	build.zig.zon, zpack --version	Any release
Format	Byte 4 of every archive, format.version	The archive layout changes incompatibly

zpack is at 0.0.2; the format is at 1. They move independently. See compatibility for what would move the format version and what would not.

While zpack is pre-1.0, the library API may change between releases. The archive format is versioned separately and does not move with it.

After a release

Consumers pin by tag:

zig fetch --save git+https://github.com/masonschafercodes/zpack#v0.1.0

Update the version referenced in the library overview and the README when it changes, so the copy-pasteable line stays current.