release

发布新版本（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 以来的变更

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 顶部当前版本，按语义化递增：