From f2c15e6e5aad1a77504e02f9d9d7f69d102bde1f Mon Sep 17 00:00:00 2001 From: Ben Vinegar Date: Thu, 10 Sep 2026 09:06:01 -0400 Subject: [PATCH 1/2] docs(release): gate Homebrew availability claims --- .changeset/tender-ravens-wait.md | 2 ++ skills/hunk-release/SKILL.md | 52 ++++++++++++++++++++++++++++++-- 2 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 .changeset/tender-ravens-wait.md diff --git a/.changeset/tender-ravens-wait.md b/.changeset/tender-ravens-wait.md new file mode 100644 index 000000000..a845151cc --- /dev/null +++ b/.changeset/tender-ravens-wait.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/skills/hunk-release/SKILL.md b/skills/hunk-release/SKILL.md index ae2c29972..66c312cef 100644 --- a/skills/hunk-release/SKILL.md +++ b/skills/hunk-release/SKILL.md @@ -193,7 +193,7 @@ Draft the final body from the released changelog and actual branch diff. Replace - Open with one short paragraph describing the release's product theme and user impact. - Group a small number of meaningful changes under descriptive headings. Explain what users can now do; do not restate commit titles or reproduce the changelog. -- Include both upgrade and npm installation instructions using the exact release: `hunk update ` for existing managed installs and `npm install -g hunkdiff@` for npm installs or first-time npm users. Add other installation-method-specific guidance only when relevant. +- Include both upgrade and npm installation instructions using the exact release: `hunk update ` for npm- and curl-managed installs and `npm install -g hunkdiff@` for npm installs or first-time npm users. Homebrew cannot select an exact version: tell its users to run plain `hunk update` only after the Homebrew readiness gate below passes, or label Homebrew propagation as pending. - Add a clearly labeled compatibility section for runtime requirements, changed CLI interpretation, extension API variants, migrations, or other upgrade risks. - Add a **Community contributors** section that names every external contributor in the release, links each relevant PR, and briefly describes their contribution. Derive this from the actual release diff; do not limit acknowledgment to first-time contributors and do not bury contributors in an autogenerated list. - Preserve a complete PR inventory inside a collapsed GitHub `
` block after the editorial sections. Use one concise bullet per merged PR with its author and link, include maintenance work there, and verify the list against the actual previous-tag comparison. The collapsed inventory is for completeness; it does not replace the curated highlights or contributor acknowledgments. @@ -247,7 +247,55 @@ Open the public release in a browser and verify inline playback, final notes, an ## 6. Distribution channels -Only stable releases that advance `latest` should propagate to Homebrew and mise. Let Homebrew Autobump update `Homebrew/homebrew-core`; use `brew bump-formula-pr` only if maintainers request it or Autobump stalls. Verify mise against fresh registry data: +Only stable releases that advance `latest` should propagate to Homebrew and mise. Let Homebrew Autobump update `Homebrew/homebrew-core`; use `brew bump-formula-pr` only if maintainers request it or Autobump stalls. + +Treat Homebrew availability as a release-announcement gate, not as an immediate consequence of the tag workflow. The tag publishes GitHub and npm artifacts, while Homebrew detects the release on its own schedule and merges a separate formula PR. Before a broad announcement that names Homebrew or recommends `hunk update` without qualifying the install method, read the live formula API and require its stable version to match: + +```sh +version=X.Y.Z +formula_version=$( + curl -fsSL https://formulae.brew.sh/api/formula/hunk.json | + bun -e 'console.log(JSON.parse(await Bun.stdin.text()).versions.stable)' +) +printf 'Homebrew formula: %s (release: %s)\n' "$formula_version" "$version" +test "$formula_version" = "$version" +``` + +If the gate fails, either hold the broad announcement or explicitly say that Homebrew is still propagating and offer npm or the install script meanwhile. Check for an open or merged Autobump PR: + +```sh +gh api --method GET /search/issues \ + -f q="repo:Homebrew/homebrew-core is:pr in:title \"hunk $version\"" \ + --jq '.items[] | [.html_url, .state, .title] | @tsv' +``` + +Determine the next expected Autobump scan from Homebrew's live workflow rather than relying on a remembered cadence. This command prints the current cron expression and, while Homebrew retains its present three-hour schedule, the next nominal UTC scan. Scheduled GitHub Actions can start late, so report this as an estimate rather than an availability promise: + +```sh +autobump_workflow=$( + gh api repos/Homebrew/homebrew-core/contents/.github/workflows/autobump.yml \ + --jq .content | base64 --decode +) +autobump_cron=$( + printf '%s\n' "$autobump_workflow" | + awk -F'"' '/^[[:space:]]*- cron:/ { print $2; exit }' +) +printf 'Homebrew Autobump schedule: %s\n' "$autobump_cron" +AUTOBUMP_CRON="$autobump_cron" bun -e ' + const cron = process.env.AUTOBUMP_CRON; + if (cron !== "45 1-23/3 * * *") { + console.error("Homebrew changed its Autobump schedule; inspect the workflow before announcing."); + process.exit(1); + } + const next = new Date(); + next.setUTCSeconds(0, 0); + do next.setUTCMinutes(next.getUTCMinutes() + 1); + while (next.getUTCMinutes() !== 45 || (next.getUTCHours() - 1) % 3 !== 0); + console.log(`Next nominal Homebrew Autobump scan: ${next.toISOString()}`); +' +``` + +After the formula version matches, run `brew update`, verify `brew info hunk` reports the release, and only then describe Homebrew as available. Verify mise independently against fresh registry data: ```sh MISE_AQUA_BAKED_REGISTRY=false mise latest hunk From 81e291cd95672fda2597dfe57fe4612151d2c9fb Mon Sep 17 00:00:00 2001 From: Ben Vinegar Date: Thu, 10 Sep 2026 11:11:49 -0400 Subject: [PATCH 2/2] docs(release): keep Homebrew check announcement-only --- skills/hunk-release/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/hunk-release/SKILL.md b/skills/hunk-release/SKILL.md index 66c312cef..9ff50479c 100644 --- a/skills/hunk-release/SKILL.md +++ b/skills/hunk-release/SKILL.md @@ -249,7 +249,7 @@ Open the public release in a browser and verify inline playback, final notes, an Only stable releases that advance `latest` should propagate to Homebrew and mise. Let Homebrew Autobump update `Homebrew/homebrew-core`; use `brew bump-formula-pr` only if maintainers request it or Autobump stalls. -Treat Homebrew availability as a release-announcement gate, not as an immediate consequence of the tag workflow. The tag publishes GitHub and npm artifacts, while Homebrew detects the release on its own schedule and merges a separate formula PR. Before a broad announcement that names Homebrew or recommends `hunk update` without qualifying the install method, read the live formula API and require its stable version to match: +Treat Homebrew availability as an announcement check only. Never delay or fail the tag, npm publication, GitHub release, changelog, release notes, video, or other release completion work because Homebrew is pending. Homebrew detects the published release on its own schedule and merges a separate formula PR. Immediately before an external promotional announcement that names Homebrew or recommends `hunk update` without qualifying the install method, read the live formula API and require its stable version to match: ```sh version=X.Y.Z @@ -261,7 +261,7 @@ printf 'Homebrew formula: %s (release: %s)\n' "$formula_version" "$version" test "$formula_version" = "$version" ``` -If the gate fails, either hold the broad announcement or explicitly say that Homebrew is still propagating and offer npm or the install script meanwhile. Check for an open or merged Autobump PR: +If the check fails, still mark the software release complete, but hold the external promotional announcement unless it explicitly says that Homebrew is still propagating and offers npm or the install script meanwhile. Check for an open or merged Autobump PR: ```sh gh api --method GET /search/issues \