/hunk-release

name: hunk-release
description: Prepares, publishes, verifies, and curates Hunk releases. Use for release metadata, benchmarks, tags, publishing, release videos, backports, or recovery.
metadata:
  internal: true

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 bun.lock 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 "$