Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Productivity

release

Cut a new HyperCapslock release end-to-end — write cumulative bilingual notes, run bump-version.sh, watch CI, verify Homebrew cask cascade.

XueshiQiao · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add XueshiQiao/HyperCapslock --skill release

About this skill


name: release description: Cut a new HyperCapslock release end-to-end — write cumulative bilingual notes, run bump-version.sh, watch CI, verify Homebrew cask cascade. disable-model-invocation: true

Release HyperCapslock

End-to-end release routine. Owns the full chain from notes through Homebrew cask propagation. Treat the user to a checkpoint at each numbered phase — show what you're about to do, then execute.

The release flow shares conventions with the AnyDrag project (.claude/skills/release/SKILL.md there): cumulative HTML release notes, bare-@mention contributor credit, repository_dispatch to shared tap, etc. The blueprint is documented in XueshiQiao/macos-app-scaffold.

Phase 0 — Validate state

  1. git status — bail if there are uncommitted changes that aren't yours to ship.
  2. git log --all --oneline -10 — list local-only branches whose commits aren't on main yet. Cherry-pick (not merge) if you want them in this release; that preserves the linear history of chore(release): YY.MM.build + Update cask for hypercapslock commits.
  3. gh issue list --repo XueshiQiao/HyperCapslock --state open — note any open issues that the new release likely closes. You'll close these in Phase 6.

Phase 1 — Prepend this version's notes to RELEASE_NOTES.html

The file is cumulative — every past version stays in it. You add a NEW per-version block at the TOP. Two <h3> sections, EN first then 更新内容 (matched by the heading shape the CI extractor + Sparkle appcast both rely on).

Pick the version first (it determines the heading text). CalVer is YY.MM.<build>:

  • YY.MM = current UTC year + month (e.g. 26.05).
  • <build> = current CURRENT_PROJECT_VERSION in project.yml + 1.

Then prepend:

<h3>What's New in YY.MM.<build></h3>
<ul>
  <li><b>Feature name</b> — Plain-English description, ≤2 sentences. Credit contributors with a BARE @handle (not an <a> link — see below).</li>
  ...
</ul>

<h3>YY.MM.<build> 更新内容</h3>
<ul>
  <li><b>功能名称</b> — 简体中文描述。贡献者用 @handle 标注(同样裸写,不要包 <a>)。</li>
  ...
</ul>

Contributor credit convention: write a bare @handle, not <a href="...">@handle</a>. The CI uses each version's section as the GitHub Release body; a bare handle lands the contributor in the release's Contributors avatar list and gets autolinked. A handle wrapped in <a> is skipped by GitHub's autolinker, so neither happens. Renders as plain text in Sparkle — acceptable. #N issue/PR refs CAN stay as <a> links so they're clickable inside Sparkle too.

Notification: a release-body @mention is credit, not a notification — GitHub doesn't reliably ping. The reliable ping happens in the Phase 6 issue comment, which must @mention them.

Translation accuracy: write each language directly, don't translate word-for-word. Mirror structure (same bullets, same order, same <b> headers), but use natural phrasing per locale. The @handle stays identical across languages — it's a handle, not text.

scripts/bump-version.sh warns at Phase 3 if there's no <h3>What's New in <new-version></h3> block in the file yet. Heed the warning before pushing.

Phase 2 — bump-version.sh (no --push)

Leave the RELEASE_NOTES.html edits from Phase 1 uncommitted — the script folds them into the same release commit.

scripts/bump-version.sh

What it does:

  • Computes the new version from YY.MM.<cur_build+1>.
  • Refuses to run if the working tree has changes other than RELEASE_NOTES.html. (Uncommitted notes edits are expected and welcome.)
  • Warns if RELEASE_NOTES.html has no block for the new version yet (Phase 1 not yet done — fix it before continuing).
  • Edits MARKETING_VERSION and CURRENT_PROJECT_VERSION in project.yml.
  • Stages project.yml + RELEASE_NOTES.html and commits with message chore(release): YY.MM.<build>, then tags vYY.MM.<build>.

Do NOT pass --push yet — sanity-check first.

Phase 3 — Sanity-check then push

# Confirm what was bumped + tagged matches HEAD.
git show --stat HEAD
git tag --points-at HEAD     # → vYY.MM.<build>

# Tag MUST point at the same commit as HEAD; if not, fix before pushing.
[ "$(git rev-parse "vYY.MM.<build>")" = "$(git rev-parse HEAD)" ] || echo "TAG MISMATCH — DO NOT PUSH"

# Push main first, then the tag — gives CI a clean view.
git push origin main
git push origin vYY.MM.<build>

Tagging triggers .github/workflows/build.yml which: builds universal → signs (inside-out, including embedded Sparkle.framework) → notarizes → staples → DMG → signs DMG with Sparkle EdDSA → writes appcast.xml (embeds the WHOLE RELEASE_NOTES.html into <description> CDATA) → extracts this version's section into release_body.html → publishes GitHub Release with the DMG + appcast.xml + latest.json attached and the per-version HTML as the body → fires repository_dispatch to XueshiQiao/homebrew-tap (event update_cask).

Gotcha — tags don't follow rebase. If origin moved while you were preparing, git pull --rebase must happen BEFORE the tag is created, not after. The sanity-check [ "$(git rev-parse <tag>)" = "$(git rev-parse HEAD)" ] catches the mismatch.

Phase 4 — Watch CI

RUN=$(gh run list --repo XueshiQiao/HyperCapslock --workflow build.yml --limit 5 --json databaseId,headBranch --jq '.[] | select(.headBranch=="vYY.MM.<build>") | .databaseId' | head -1)
gh run watch "$RUN" --repo XueshiQiao/HyperCapslock --exit-status

If conclusion isn't success, stop and report. The cascades in Phase 5 won't fire on a failed build.

Phase 5 — Verify the cask cascade (now automatic)

Don't manually bump the cask. The release workflow's Trigger Homebrew Tap Update step fired the dispatch. Verify:

# Tap regeneration of Casks/hypercapslock.rb
gh run list --repo XueshiQiao/homebrew-tap --workflow update-casks.yml --limit 1 \
  --json status,conclusion,createdAt,displayTitle
gh api repos/XueshiQiao/homebrew-tap/contents/Casks/hypercapslock.rb -
Read the complete source ↗