release

name	release
description	自动化项目的版本发布流程，包括版本号自增、ChangeLog 提取与汇总、代码提交、打标签以及推送到远程仓库。

Release Skill

此 Skill 旨在提供一个标准化的发布流程。它通过脚本自动处理繁琐的操作，并利用 AI 总结用户可感知的改动。

目录结构

• scripts/bump_version.py: 自动更新 pubspec.yaml 版本号。
• scripts/get_commits.py: 提取用于发布日志的 Git 提交记录。发布 beta 时从上一次发布开始提取；发布非 beta 正式版时从上一个正式版开始提取，并自动过滤中间的 # release: 提交。
• scripts/format_release.py: 格式化发布日志模板。

使用流程

1. 准备阶段

   • 检查当前分支是否为发布分支（通常是 master/main）。
   • 确认工作区是干净的（没有未提交的改动）。

2. 版本号更新

   • 运行 python3 scripts/bump_version.py 或者带上目标版本 python3 scripts/bump_version.py 2.20.2-beta。
   • 如果用户提供了版本号，则使用用户指定的版本号，并且自动保留并增加构建号（例如从 +513 变为 +514）。
   • 如果未提供版本号，脚本会自动在当前版本号的基础上增加一个小版本号（patch），并同样增加构建号，且保留原有的 -beta 等预发布后缀。

3. 生成发布日志

   • 运行 python3 scripts/get_commits.py 获取原始提交记录（也可显式传入版本：python3 scripts/get_commits.py 2.20.2）。
   • 提交范围规则：
     • 如果目标版本包含 beta，则从最近一次发布（# release:）到 HEAD。
     • 如果目标版本不包含 beta，则从上一个正式版（不含 beta）到 HEAD，确保正式版汇总覆盖期间所有 beta 阶段改动。

• 将记录提供给 AI，根据 scripts/format_release.py 的定义，总结出用户可感知的改动。
• 改动分类应包括：🎉Highlights、✨新增功能、🐛修复问题、🔧性能优化、📋其它。架构优化和技术细节无需列入用户日志。
• **非常重要：**AltStore/AltSource 源信息更新、源地址变更、源元数据同步这类分发侧维护内容，不属于用户可感知改动，不要写入发布日志的任何分类。
• **非常重要：**如果某个分类下没有相关改动，必须直接省略该分类，绝对不要写“暂无”或“无”。
• **非常重要：**生成的发布日志必须经过用户确认后，再进行 Commit 操作。

4. 提交与标注

   • 注意：在 Git 提交信息和打标签时，版本号必须省略 + 及其后面的构建号（例如：版本号 2.19.4+510 对应 2.19.4，版本号 2.20.2-beta+514 对应 2.20.2-beta）。pubspec.yaml 中则保留完整版本号。
   • 提交改动：# release: {基础版本号}\n\n{发布日志内容}。
   • 打标签：v{基础版本号}。

5. 推送

   • 将代码和标签推送到远程仓库：git push origin {branch} --tags。

注意事项

• 提交消息必须使用真实的换行，而不是 \n 字符串。
• 提交消息中如果包含反引号（例如 `3.42.0`），不要直接放进双引号命令参数里，避免被 shell 当作命令替换导致内容丢失。
• 推荐做法：先把完整提交信息写入临时文件，再用 git commit -F <file>；或使用单引号/安全转义，确保正文按原文写入。
• 确认发布日志内容后，再进行 Commit 操作。