AnyDrag Release Routine

Release AnyDrag

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

The release flow shares conventions with the HyperCapslock project (.claude/skills/release/SKILL.md there): cumulative HTML release notes, bare-@mention contributor credit, repository_dispatch to shared tap. The generalized 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 appcast for vYY.MM.<build> (CI bot) + Update cask for anydrag (tap bot) commits.
3. gh issue list --repo XueshiQiao/AnyDrag --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>. 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.

Leave the edited RELEASE_NOTES.html uncommitted — Phase 2's script folds it into the release commit.

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

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) → commits appcast.xml back to main (for legacy users still pinned to the raw.githubusercontent URL) → uploads appcast.xml + latest.json + DMG as release assets (so the new releases/latest/download/appcast.xml URL also resolves) → extracts this version's section into release_body.html → publishes GitHub Release with that as the body → fires repository_dispatch to XueshiQiao/homebrew_tap (event update_cask).

Gotcha — tags don't follow rebase. Hit live in earlier releases: pre-release prep had a git pull --rebase after git tag, so the tag stayed at the pre-rebase orphan commit. Pushing it triggered CI, the build/sign/notarize/DMG steps all succeeded, but the appcast step's final git push origin HEAD:main failed with ! [rejected] HEAD -> main, the GitHub Release was never created, and gh release view returned "release not found." Recovery: delete the bad tag locally and remotely (git push origin :refs/tags/vX; git tag -d vX), retag at the correct commit, push again. Prevention: tag after rebase (which bump-version.sh enforces by requiring a clean tree minus RELEASE_NOTES.html), and run the sanity-check above before pushing.

Phase 4 — Watch CI

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

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