Hunk Release Workflow

Hunk release workflow

Maintainer-focused and source-checkout only. The tag workflow publishes hunkdiff plus five platform packages, attests the binary archives, and creates the GitHub release.

Safety

• Ask when the version, release branch, previous tag, or channel is ambiguous.
• Get explicit confirmation before pushing a tag, triggering publication, or editing a public release.
• Never reuse an npm version or move a tag after publication.
• Never bypass a benchmark regression without an approved, recorded reason.
• Never retry a partial publish before inventorying every package and artifact.

1. Confirm the release

Record the version, tag, branch, previous tag, and expected channel:

• newer stable: npm latest and GitHub Latest;
• prerelease: npm beta, not GitHub Latest;
• older-series backport: npm backport-X.Y, leaving both latest pointers unchanged.

For backports, include only commits present between the previous tag and the release tip on that maintenance branch. Inspect .changeset/pre.json before changing prerelease state.

2. Prepare

Start from a clean, current release branch:

git status --short --branch
git fetch origin --tags --prune
git tag --sort=-version:refname | head -10
bun install --frozen-lockfile
bun run changeset:status

Read the pending Changesets, then generate metadata and the published release notes:

bun run release:version
bun run generate:changelog
git diff -- package.json packages CHANGELOG.md .changeset website

Verify the intended versions, consumed Changesets, and new changelog section. Do not force a bump by hand-editing generated versions.

generate:changelog projects CHANGELOG.md into hunk.dev/changelog. Never hand-edit its output under website/src/content/docs/changelog/, website/public/changelog/, website/releases/dates.json, or website/releases/latest.json. For a minor or major release, add the hand-authored parts to website/releases/notes.json under the major.minor key and regenerate:

• summary — one sentence; replaces the changelog's ### Highlights lead paragraph on the page.
• tagline — short phrase for the landing-page release ribbon.
• links — docs pages the highlights describe, rendered as "Related documentation".
• video — mp4 plus optional webm, poster, duration, and title, filled in at step 5.

The release tag does not exist yet at this point. A stable version is rendered as Unreleased without an install command, while an undated prerelease remains off the site entirely; the tag date is picked up by the next generation. Recorded dates in website/releases/dates.json are never recomputed, which is what lets check:changelog gate CI without Git tags.

Generate and compare the committed release benchmark:

bun run bench:release
bun run bench:release:compare

A material regression blocks the release unless the user approves an acceptedRegressions entry following benchmarks/release/README.md.

Run the validation required by AGENTS.md, plus the release packaging checks:

bun run check:docs
bun run check:changelog
bun run check:pack
bun run build:prebuilt:npm
bun run check:prebuilt-pack
bun run smoke:prebuilt-install

Commit the generated metadata and benchmarks/release/bench-X.Y.Z.json, then follow normal review policy. The Firecracker evidence must come from that reviewed release tip, not the pre-generation commit. Push the reviewed tip before using the manual workflow.

Run the full Firecracker install compatibility suite once from the clean reviewed release tip on a Linux x64 host with working KVM, either locally or through the manually dispatched install-vm.yml workflow:

set -euo pipefail
mkdir -p tmp/install-vm/runs
result_dir=$(mktemp -d tmp/install-vm/runs/release-XXXXXXXX)
bun run test:install-vm -- --output "$result_dir"
bun run ./test/cli/install-vm/validate-release-result.ts "$result_dir/result.json"

The explicit output directory prevents a failed invocation from falling back to stale evidence. The validator requires the complete checked-in scenario manifest, passing statuses, and the current checkout's source identity. A skipped result does not satisfy release validation. For the manual workflow, dispatch the full suite from the reviewed tip, download its result.json beneath the ignored tmp/install-vm/ directory of a checkout at that exact tip, and run the validator there; a green job alone is insufficient because unsupported runners may use the intentional skip path. Firecracker validates Linux x64 packaging behavior, while the existing native release jobs remain responsible for macOS, Windows, and other architectures. Wait for required CI before continuing.

3. Tag and publish

Immediately before tagging, fail unless the reviewed branch tip is clean and matches its remote:

set -euo pipefail
branch=$(git branch --show-current)
test -n "$branch"
git fetch origin "$branch" --tags
test "$(git rev-parse HEAD)" = "$(git rev-parse "origin/$branch")"
if [ -n "$(git status --porcelain --untracked-files=all)" ]; then
  git status --short
  exit 1
fi
git log -1 --format='%H %s'

Present the tag, commit, benchmark result, validation, and release highlights. After explicit confirmation:

version=X.Y.Z
tag="v$version"
git tag -a "$tag" -m "$tag"
git push origin "$tag"

The tag push starts .github/workflows/release-prebuilt-npm.yml. Find only the run for that tagged commit and propagate failure:

release_sha=$(git rev-parse "$tag^{}")
run_id=$(
  gh run list \
    --workflow release-prebuilt-npm.yml \
    --event push \
    --commit "$release_sha" \
    --limit 1 \
    --json databaseId \
    --jq '.[0].databaseId // empty'
)
test -n "$run_id"
gh run view "$run_id" --json url,status,conclusion
gh run watch "$run_id" --exit-status

If lookup is empty, repeat it after GitHub registers the run; never select an unrelated run. Success requires the benchmark, all builds, staging smoke test, npm publish, attestation, and GitHub release jobs.

4. Verify publication

Check the meta-package, platform packages, dist-tags, release body, and five binary archives:

npm view "hunkdiff@$version" version
for package in \
  hunkdiff-darwin-arm64 hunkdiff-darwin-x64 \
  hunkdiff-linux-arm64 hunkdiff-linux-x64 \
  hunkdiff-windows-x64; do
  npm view "$package@$version" version
done
npm view hunkdiff dist-tags --json
gh release view "$tag" --json tagName,name,isPrerelease,url,assets,body

Stop if versions, channel, tag, archives, or attestations disagree.

Then record the tag date and publish the release notes. The published page is what the update notice and the GitHub release body point at, so it is part of the release, not follow-up work:

bun run generate:changelog
bun run generate:og
git diff --stat -- website

This backfills the new tag's date, publishes its notes, and redraws the social cards whose contents changed. Stable releases also add the install command and move the landing-page ribbon; prereleases publish a clearly labeled series without advancing either stable surface. Commit it to main — the diff should only touch website/releases/, website/src/content/docs/changelog/, website/public/changelog/rss.xml, and the redrawn cards under website/public/changelog/og/. Run this for backports too: they publish into their older series without advancing the latest stable release.

Prereleases publish to hunk.dev/changelog after their tag exists. A beta contributes its series page, exact version anchor, index row, feed item, and social card, while the stable latest marker, landing ribbon, and default install instructions continue to name the newest stable release.