release-workflow

name	release-workflow
description	本技能应在 GitHub 项目发布新版本时使用，覆盖版本号管理、CHANGELOG 同步、Release Notes 撰写、tag 创建、CI 构建监控、发布验证和历史清理全流程。适用于桌面应用、CLI 工具、Web 应用、库/SDK 等任何基于 GitHub 的软件项目。当用户提到"发布"、"release"、"打 tag"、"新版本"、"更新版本号"、"写 release notes"、"发布失败了"、"CI 挂了"时触发。不要用于非 GitHub 项目（如纯 GitLab / Gitea 项目）或无需 CI 的手动发布场景。
license	MIT License - 详见 LICENSE.txt

Release Workflow

软件项目的全流程发布工作流。适用于 GitHub 上的任何类型项目。

适用场景

GitHub 项目的完整发布周期：从版本号确定到 CI 构建验证。CI 故障排查（references/ci-troubleshooting.md）和特定项目类型指南（references/ 下各文档）作为发布流程的补充参考。

项目配置

config/projects.yaml 集中管理各项目的发布配置（仓库、平台、自动更新、排除产物等）。发布时先读取对应项目配置，按配置决定构建矩阵和预期产物。模板见 config/projects.example.yaml。

发布前检查

检查项	说明
工作区干净	git status 无未提交变更
版本号一致	所有版本号文件（package.json / Cargo.toml / pyproject.toml 等）与 CHANGELOG.md 最新条目一致
CHANGELOG 已更新	包含目标版本的结构化条目
CI 工作流存在	.github/workflows/ 中有 release 相关工作流且 tag 触发配置正确

任一条件不满足，先修复再继续。

发布流程

第 1 步：确定版本号

从用户处获取或从 CHANGELOG.md 读取目标版本号。

统一所有版本号文件（按项目类型选取）：

• Node.js 项目：package.json → version
• Rust 项目：Cargo.toml → version
• Python 项目：pyproject.toml → version
• 桌面应用：对应配置文件（如 Tauri 的 tauri.conf.json）
• CHANGELOG.md → 最新 ## [x.y.z] 条目

版本号规则（SemVer）：

类型	示例	适用场景
PATCH	0.3.7 → 0.3.8	Bug 修复、小改进
MINOR	0.3.x → 0.4.0	新功能、向后兼容
MAJOR	0.x → 1.0.0	重大架构变更、破坏性改动

第 2 步：生成 Release Notes

信息来源有两个，必须综合使用：

来源 1 — CHANGELOG.md：结构化的变更分类（Added / Changed / Fixed 等）

来源 2 — git log：两个 tag 之间的 commit 历史，补充上下文和细节

# 获取上一个 tag
PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")

# 查看 commit 历史
git log ${PREV_TAG}..HEAD --oneline

# 查看详细变更（含 PR 链接）
git log ${PREV_TAG}..HEAD --format="- %s (%h)"

综合两个来源，按模板组织 Release Notes。模板和格式指南见 references/release-notes-guide.md。

第 3 步：提交并打 Tag

# 确保所有变更已提交
git status

# 打 tag
git tag "vX.Y.Z"

# 推送 tag 触发 CI
git push origin "vX.Y.Z"

如果有同名旧 tag（如发布失败后重试）：

git push origin :refs/tags/vX.Y.Z
git tag -d vX.Y.Z 2>/dev/null
git tag vX.Y.Z
git push origin vX.Y.Z

第 4 步：监控 CI 构建

# 查看构建状态
gh run list --limit 3

# 各平台 job 状态
gh run view <RUN_ID> --json jobs --jq '.jobs[] | "\(.name): \(.conclusion)"'

# 失败日志
gh run view <RUN_ID> --log-failed

项目类型的特定构建产物和验证方法，见 references/ 下对应文档。

第 5 步：更新 Release Notes

CI 构建成功后，用第 2 步准备的草稿更新 GitHub Release：

gh release edit vX.Y.Z --repo <owner>/<repo> --notes "$(cat <<'EOF'
<Release Notes 内容>
EOF
)"

第 6 步：验证

# 检查产物是否完整
gh release view vX.Y.Z --json assets --jq '.assets[].name'

对照 config/projects.yaml 中该项目的配置检查：

1. 预期产物是否齐全（根据 platforms 和 auto_update 推导）
2. exclude_assets 中列出的产物是否意外出现
3. 产物命名是否符合规范

第 7 步：清理

• 删除失败的 Actions runs：gh run delete <ID>
• 清理旧的 draft release（如有）
• 确认镜像同步是否成功（如已配置）

特定项目类型指南

项目类型	参考文档
Tauri 桌面应用	references/tauri-release.md

检查清单

发布完成后确认：

• 所有平台 / 矩阵构建全部成功
• GitHub Release 产物完整
• Release Notes 已更新
• 镜像同步成功（如已配置）
• 旧的失败 Actions runs 已清理
• 项目文档已更新（TASKS / DECISIONS / CHANGELOG 等）
• tag 指向正确的 commit