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 releaseAbout 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
git status— bail if there are uncommitted changes that aren't yours to ship.git log --all --oneline -10— list local-only branches whose commits aren't onmainyet. Cherry-pick (not merge) if you want them in this release; that preserves the linear history ofchore(release): YY.MM.build+Update cask for hypercapslockcommits.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>= currentCURRENT_PROJECT_VERSIONinproject.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.htmlhas no block for the new version yet (Phase 1 not yet done — fix it before continuing). - Edits
MARKETING_VERSIONandCURRENT_PROJECT_VERSIONinproject.yml. - Stages
project.yml+RELEASE_NOTES.htmland commits with messagechore(release): YY.MM.<build>, then tagsvYY.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 ↗