Release automation: tag-triggered GitHub Release + docs/audit CI jobs

[koko1123]

Motivation

Releases (v0.4.0, v0.5.0) are currently cut by hand. CI also has gaps found during the recent dependency work: the docs site is not built in CI (Next.js breakage only surfaces on Vercel) and there is no dependency-audit job (the docs npm tree accumulated 16 vulnerabilities silently).

Scope

• .github/workflows/release.yml: on v* tag push -- verify build.zig.zon version matches the tag, extract that version's CHANGELOG section, create the GitHub Release with it
• Add to ci.yml: a docs job (cd docs && pnpm install && pnpm build) and a pnpm audit job (fail on high severity)
• Path-filter so Zig-only changes skip the docs jobs

Pointers

CHANGELOG.md follows Keep-a-Changelog headings -- section extraction is a small awk/sed step.

[Mario-SO]

I could tackle this one. How exactly would you like the experience to be? I get the on v* tag push but dont get the rest...

Just as a suggestion too, at my job, we have a regex matching for the prefix bump(major|minor|patch) so if you include that in a commit, it will up the corresponding version and trigger the CI for release and such, I find it quite nice and you dont have to worry about manually tagging and all, it is pretty automatic.

you can be pushing stuff normally, when you feel like it deserves a new version, you prefix the next commit with that pattern, and thats it.

[koko1123]

@Mario-SO yes please, would love your help on this. Your instinct is spot on — the goal is exactly that: stop hand-tagging, and make "this deserves a release" the only manual decision. I'd just reach for the standardized version of what you described rather than a custom commit prefix, because it composes better with this repo's PR-only branch protection.

Recommended approach: release-please

release-please is the productized form of your bump(...) idea. It watches main, reads Conventional Commits (feat: → minor, fix: → patch, feat!:/BREAKING CHANGE: → major), and keeps an open "Release PR" that bumps the version and regenerates CHANGELOG.md. You merge that PR when it feels ready → it tags and cuts the GitHub Release automatically.

Why this over a single-commit prefix:

• It derives the bump from all commits since the last tag, so it survives squash-merges and reverts (a lone prefix commit doesn't).
• It fits our PR-only flow perfectly — the "merge the release PR" click is the human decision you wanted, no direct pushes to main.
• It writes the changelog for us from the commit history.

The Zig-specific must

The one thing release-please won't do out of the box, and the most important guard for us: build.zig.zon's .version has to match the tag, or zig fetch against the release is broken. release-please handles arbitrary files via extra-files + annotation comments. Concretely:

// build.zig.zon
.version = "0.7.0", // x-release-please-version

and list it (plus the README/docs install URLs that carry #vX.Y.Z) under extra-files so they get bumped in the same Release PR. release-type: simple is the right base type for a non-npm/cargo project.

Scope for this issue

1. .github/workflows/release-please.yml — the action on push: main, release-type: simple, with extra-files covering build.zig.zon, README.md, and docs/content/docs/installation.mdx.
2. On the release being published (or on the tag it creates), run the existing test matrix and attach nothing fancy — a source release is fine for a zig fetch library.
3. While you're in CI, the two gaps from the issue body are worth folding in as separate jobs (or a follow-up): a docs build job (cd docs && pnpm build — Next.js breakage currently only shows up on Vercel) and a pnpm audit job (the docs tree silently accumulated vulns once already).

We'd also want a short CONTRIBUTING note that commit messages should follow Conventional Commits so the bumps land correctly.

If you want to start with just #1 (the release-please workflow + the build.zig.zon annotation), that's the highest-value piece and a clean PR on its own — happy to review. Thanks for picking this up!

[Mario-SO]

Doing some cleanup on my github homescreen, this one still appears there but the PR was merged some time ago. @koko1123 you can close this issue 🫡