release
/release
Prowadzi przez wydanie Usage4Claude: zbiera zmiany, pisze CHANGELOG i notatki, podbija wersję i uruchamia publikację CI.
- Autor
- f-is-h ↗
- Repozytorium
- usage4claude ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 29.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 2
Brak sygnałów. Repozytorium zmienione 29.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Prowadzi przez wydanie Usage4Claude: zbiera zmiany, pisze CHANGELOG i notatki, podbija wersję i uruchamia publikację CI.
Wyzwalacze z opisu
Oryginalny opis (EN)
发布 Usage4Claude 新版本时使用。当用户说“发布新版本 / 发版 / 出新版 / release / 打 tag 发布 / 准备发版材料”等,用本 skill 引导完成从收集变更、编写 CHANGELOG 与 RELEASE_NOTES、更新版本号、编译验证,到发版 commit、CI 自动发布的完整流程。
Jak działa
- 必须先记住的架构事实
- 两份材料的分工(关键)
- 流程
- 发版前的安全测试(不真正发布)
- 红线清单
- 相关文档
Podgląd SKILL.md
---
name: release
description: 发布 Usage4Claude 新版本时使用。当用户说“发布新版本 / 发版 / 出新版 / release / 打 tag 发布 / 准备发版材料”等,用本 skill 引导完成从收集变更、编写 CHANGELOG 与 RELEASE_NOTES、更新版本号、编译验证,到发版 commit、CI 自动发布的完整流程。
---
# 发布新版本(Release)
Usage4Claude 采用 **CI 自动发布**:向 `main` push 一个满足条件的 commit 后,
GitHub Actions(`.github/workflows/release.yml`)自动完成构建、签名、发 Release、
更新 Sparkle 更新源。你(Claude)的职责是准备好发版材料并引导用户完成触发,
**不代替用户执行发版 commit 与 push**。
> 若根目录存在 `NEXT_RELEASE.md`,说明本次发版有一次性特殊情况,**先读它**再按本流程走。
## 必须先记住的架构事实
- **两份发布材料,各司其职**(详见下一节分工表):
- `CHANGELOG.md` — 完整技术档案 + **版本号权威源**,不进 Sparkle。
- `docs/RELEASE_NOTES.md` — 面向用户的发布说明,CI 提取当前版本段落后**同时**注入
Sparkle 弹窗(`appcast.xml` 的 `<description>`)和 GitHub Release 正文。
- **触发条件**:commit message 含 `[release]`/`[RELEASE]`,push 到 `main`,且本次改动
包含 `CHANGELOG.md` 或 `docs/RELEASE_NOTES.md`(发版通常两者都改)。
- **Sparkle 弹窗内容来自 docs/RELEASE_NOTES.md**(不是 CHANGELOG)。用户在应用内“检查更新”
看到的就是 RELEASE_NOTES 当前版本段落。
- **docs/RELEASE_NOTES.md 必须有当前版本段落**:否则 Sparkle/Release 正文会为空。CI 的
validate 阶段会 `grep "^## [X.Y.Z]"` fail-fast,但应发版前就写好。
- **Build 号自动跟随**:`CURRENT_PROJECT_VERSION = $(MARKETING_VERSION)`,Build 恒等于
Version。**只改 Version,绝不手动固定 Build**,否则 Sparkle 认不出新版本。
- **appcast.xml 由 CI 维护**,绝不手改。
- 详细背景见 `docs/DAILY_RELEASE_WORKFLOW.md`、`docs/SPARKLE_SETUP.md`。
## 两份材料的分工(关键)
| | CHANGELOG.md | docs/RELEASE_NOTES.md |
|---|---|---|
| 定位 | 完整技术档案 + 版本号权威源 | 面向用户的发布说明 |
| 收录范围 | **所有改动**,含内部重构、CI、安全加固 | **只留用户可感知的现象** |
| 措辞 | 可保留技术细节(JWT、actor、base64url 等) | 口语化,去技术词 |
| 致谢 | 不加 | 在相关条目末尾加 `(thanks @author, #N)` |
| CI 喂给 | 无(纯档案;validate 从它提版本号) | Sparkle 弹窗 + GitHub Release 正文 |
| 何时写 | 发版前 | 发版前(不是发布后精修) |
> 规则细节见 `docs/CHANGELOG_AND_RELEASE_NOTES_GUIDELINES.md`。
## 流程
### 1. 收集自上个 tag 以来的变更
```bash
git fetch origin # 先核对远程,避免发版已在别处完成
LAST_TAG=$(git describe --tags --abbrev=0) # 上一个发布 tag,如 v3.3.0
git log "$LAST_TAG"..HEAD --oneline # 变更概览
git log "$LAST_TAG"..HEAD --format='=== %h ===%n%B' # 完整 message(判断影响面必读)
git log "$LAST_TAG"..HEAD --merges --format='%h %s' # 合并的 PR(用于致谢)
```
逐条阅读完整 message,区分:用户可感知的现象 vs 纯内部改动。两类都进 CHANGELOG,
但只有前者进 RELEASE_NOTES。
### 2. 决定版本号
读 CHANGELOG.md 顶部当前版本,按语义化递增:
| 改动类型 | 递增 | 例 |
|---|---|---|
| 仅 Bug 修复 | patch | 3.3.0 → 3.3.1 |
| 含新功能 | minor | 3.3.0 → 3.4.0 |
| 破坏性变更 | major | 3.3.0 → 4.0.0 |
版本号不确定时用 AskUserQuestion 让用户确认。
### 3. 编写两份发布材料
**3a. CHANGELOG.md(完整技术档案)**
- 在文件顶部(`# Changelog` 与首个 `## [` 之间)插入新版本段落,日期用当天。
- 收录**所有**改动,按 `Added` / `Changed` / `Fixed` / `Security` 分类。
- **新功能的后续修改/优化/bug 修复并入该功能条目**,不在 Fixed 里重复列出。
- 每个变更点一条,不同变更点只出现一次,简洁不赘述。
- **更新文件底部版本链接**:新增
`[X.Y.Z]: https://github.com/f-is-h/Usage4Claude/releases/tag/vX.Y.Z`
**3b. docs/RELEASE_NOTES.md(面向用户 + 致谢)**
- 在文件顶部插入 `## [X.Y.Z] - 当天日期` 段落(结构同 CHANGELOG)。
- **只保留用户可感知的现象**,去技术词、口语化。
- 收集本版本对应的 **已合并 PR** 与 **已解决 Issue** 及作者,条目末尾致谢
`(thanks @author, #N)`:
```bash
gh pr view <n> --repo f-is-h/Usage4Claude --json number,title,author,state
gh issue view <n> --repo f-is-h/Usage4Claude --json number,title,author,state
```
**只对确已合并的 PR / 确已解决的 Issue 致谢**。未合并的 PR、仍 Open 且本次并未真正
修复的 Issue **不致谢**,避免误导用户(硬规则)。
两份写入文件的都是**英文**;同时在对话里给用户中文对照(不写进文件)。写好后用
AskUserQuestion 让用户确认草稿再继续。
### 4. 更新 Xcode 版本号
两处 `MARKETING_VERSION`(Debug/Release)都要改:
```bash
sed -i '' 's/MARKETING_VERSION = <旧版本>;/MARKETING_VERSION = <新版本>;/g' \
Usage4Claude.xcodeproj/project.pbxproj
grep -n "MARKETING_VERSION" Usage4Claude.xcodeproj/project.pbxproj # 确认两处都改了
```
CHANGELOG 版本与 Xcode 版本**必须完全一致**,否则 CI 的 `verify_version.sh` 会失败。
RELEASE_NOTES 也必须有同一版本段落(CI validate 会 fail-fast)。
### 5. 编译验证
```bash
xcodebuild -project Usage4Claude.xcodeproj -scheme Usage4Claude -configuration Release build 2>&1 | tail -5
```
看到 `** BUILD SUCCEEDED **` 后,核对产物版本号:
```bash
APP=$(find ~/Library/Developer/Xcode/DerivedData -name Usage4Claude.app -path '*/Release/*' | head -1)
/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "$APP/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Print :CFBundleVersion" "$APP/Contents/Info.plist" # 应与 Version 相同
```
### 6. 发版 commit + push(**commit 由用户手写**)
发版 commit message 不走日常 `COMMIT_MESSAGE_GUIDELINES` 那套,由用户手工编写。
你只提供草稿供参考,**不擅自 commit/push**——`git add`/`commit`/`push` 需用户确认后执行。
- **只写一行标题,不要正文。** CI 只取第一行(去掉 `[release]` 前缀)作为 GitHub
Release 标题;正文不被使用(Release 正文来自 RELEASE_NOTES),写了也是浪费。
- 格式:
```
[release] vX.Y.Z - 简短标题
```
- 触发前自检:commit 含 `[release]`、本次改动含 `CHANGELOG.md`/`docs/RELEASE_NOTES.md`、目标分支 `main`。
推送后 CI 触发。
### 7. 监控 CI
```bash
gh run list --workflow=release.yml --limit 3
gh run watch # 或看 https://github.com/f-is-h/Usage4Claude/actions
```
CI 三段:validate(版本校验 + RELEASE_NOTES 段落校验)→ build(构建签名,约 8 分钟)→
release(发 Release + 推 appcast.xml 回 main)。失败常见原因:版本号不一致、RELEASE_NOTES
缺当前版本段落、CHANGELOG 版本已发布过。
### 8.(可选)发布后装饰 GitHub Release 页面
CI 已用 RELEASE_NOTES 自动发布了面向用户的 Release,且 Sparkle 弹窗同源——**通常无需再做**。
若想让 GitHub Release 页面更精致(大标题、总览段落、emoji),可发布后手工编辑网页。
- 这属于 **GitHub 页面装饰**,**不回流 Sparkle**(Sparkle 已在发布时拿到 RELEASE_NOTES 段落)。
- 改的是对外公开页面,**先与用户确认再执行**。
- 页面正文结构 = 「RELEASE_NOTES 段落」+ `---` + Installation + `---` + Full Changelog,
只改第一个 `---` 上方那段,下方模板不要动。用 `gh release edit` 会整体替换正文,需先
`gh release view vX.Y.Z --json body -q .body` 取回完整正文改上半段后整体回填。
## 发版前的安全测试(不真正发布)
按影响面从小到大三档,用于在正式发版前验证:
**① 本地预览(零风险,什么都不发)**
```bash
swift test # 单元测试
xcodebuild -project Usage4Claude.xcodeproj -scheme Usage4Claude \
-configuration Release build # 能否编译
.github/scripts/verify_version.sh verify CHANGELOG.md Usage4Claude.xcodeproj # 版本号一致性
.github/scripts/generate_release_notes.sh \
.github/RELEASE_TEMPLATE.md <版本> /tmp/rn_preview.md docs/RELEASE_NOTES.md # 预览 Release 正文
./scripts/build.sh --config Release # 本地打 DMG,验证打包脚本
```
`generate_release_notes.sh` 输出里第一个 `---` **上方**那段,同时也是 **Sparkle 更新弹窗**
会显示的内容(都来自 RELEASE_NOTES)——发版前务必看一眼措辞是否面向用户。
**② `test-release` 分支(CI 构建冒烟,不发布)**
- 把改动 push 到 `test-release` 分支(commit 仍含 `[release]`)。
- CI 跑 validate + build:在 CI 环境编译、导入证书、Sparkle 签名、打 DMG。
- **跳过 release job**(`is_test=true`)→ 不打 tag、不发 Release、不碰 appcast、不 push main。
- 用途:验证 CI 能否构建出签名 DMG(本地过 ≠ CI 过,证书/Sparkle 私钥只在 CI secrets)。
DMG 作为 artifact 可下载。几乎无需清理。
**③ `workflow_dispatch` dry_run(端到端演练,产草稿)**
- 在 Actions 页面对 **main** 手动运行 workflow,勾选 `dry_run`。
- 跑完整三段,但:tag=`test-v<版本>`、Release 走 `--draft`(公众不可见)、appcast 只打印不 push。
- 用途:演练整条发布链路(含 release job 的 tag/release/appcast 逻辑)而不影响用户。
- **需清理**:`gh release delete test-v<版本> --yes` 且 `git push origin :refs/tags/test-v<版本>`。
- 注意:dry_run 必须在 main 触发才有端到端效果;在 test-release 触发会退化成 ②。
选择:只验发布材料 → ①;验 CI 构建 → ②;验整条链路 → ③。
## 红线清单
- 发版 commit 与 push **由用户执行**,你只准备材料 + 提供草稿。
- 发版前 `CHANGELOG.md` 与 `docs/RELEASE_NOTES.md` 都要有当前版本段落。
- CHANGELOG 版本号与 Xcode `MARKETING_VERSION` 必须一致。
- 只改 Version,**不碰 Build 号**(自动跟随 MARKETING_VERSION)。
- **不手改 appcast.xml**(CI 维护)。
- 致谢只给**确已合并/解决**的 PR/Issue。
- **已发布版本的 CHANGELOG / RELEASE_NOTES 段落不回改**(否则与已发内容、Sparkle 说明不一致)。
- 冒烟测试若需杀进程,用 `kill <PID>` 而非 `killall`(避免误伤用户在跑的正式版实例)。
## 相关文档
- `docs/DAILY_RELEASE_WORKFLOW.md` — 日常发版流程全文
- `docs/CHANGELOG_AND_RELEASE_NOTES_GUIDELINES.md` — CHANGELOG 与 RELEASE_NOTES 编写规范
- `docs/COMMIT_MESSAGE_GUIDELINES.md` — 日常 commit 规范(发版 commit 不适用)
- `docs/SPARKLE_SETUP.md` — Sparkle 自动更新机制
- `.github/workflows/release.yml` — CI 发布流水线
- `.github/RELEASE_TEMPLATE.md` — Release 正文固定模板(Installation 等)
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · f-is-h/usage4claude | 100 | MIT |
| josephfung/curia | 100 | MIT |
| max-sixty/worktrunk | 100 | MIT |
| gtapps/hermitd | 100 | MIT |
| gtapps/hermitd | 100 | MIT |
| anthony-chaudhary/fak | 100 | Apache-2.0 |
| tractorjuice/arc-kit | 100 | MIT |
| drvoss/everything-copilot-cli | 100 | MIT |
| sma1lboy/rove | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki eb39e5635c0b (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100release-workflow
Prowadzi wydanie projektu na GitHubie: wersję, CHANGELOG, notatki, tag, kontrolę CI i sprawdzenie stanu po publikacji. - 100ac-release
Prowadzi przepływ wydania: branch, changelog, pull request, tag i wydanie na GitHubie. - 100commit-push-release
Commituje zmiany, podbija wersję w package.json, tworzy tag vX.Y.Z i wysyła go, aby CI opublikowało wydanie. - 100release-prep
Przygotowuje wydanie cc-router: podbija wersję, pisze notatki w czterech językach, waliduje je i zatrzymuje się przed tagiem. - 100releasing
Prowadzi pełny cykl wydania: podniesienie wersji, CHANGELOG, rozbudowane notatki do wydania, tag i publikację. - 100release-version
Prowadzi przez wydanie nowej wersji: podniesienie wersji, generowanie changelogu, grupowanie commitów, tagowanie i śledzenie CI na GitHubie.