PolyHermes/scripts/README_RELEASE.md

Release 创建脚本使用说明

简介

create-release.sh 脚本用于快速创建 GitHub Release，包括：

• 创建本地和远程 tag
• 创建 GitHub Release 页面
• 支持 Pre-release 标记
• 自动触发 GitHub Actions 构建流程

前置要求

1. 安装 GitHub CLI

脚本依赖 GitHub CLI (gh) 来创建 Release。

macOS:

brew install gh

Linux:

# Ubuntu/Debian
sudo apt install gh

# 或从官网下载安装
# https://cli.github.com/

验证安装:

gh --version

2. 登录 GitHub

首次使用需要登录 GitHub：

gh auth login

按照提示完成认证。

验证登录状态:

gh auth status

3. 确保 Git 仓库配置正确

# 检查远程仓库
git remote -v

# 确保在正确的分支
git checkout main  # 或 master

使用方法

基本用法

# 在项目根目录下运行脚本

# 创建正式版本
./create-release.sh -t v1.0.1 -T "Release v1.0.1" -d "## 新功能\n- 功能1\n- 功能2"

# 创建 Pre-release（自动拼接 -beta）
./create-release.sh -t v1.0.1 -T "Release v1.0.1-beta" -d "测试版本" --prerelease

参数说明

参数	简写	说明	必需	默认值
--tag TAG	-t	版本号 tag（格式：v1.0.0）	✅ 是	-
--title TITLE	-T	Release 标题	❌ 否	使用 tag 值
--description DESC	-d	Release 描述内容	❌ 否	"Release {tag}"
--description-file FILE	-f	从文件读取 Release 描述	❌ 否	-
--prerelease	-p	标记为 Pre-release	❌ 否	false
--help	-h	显示帮助信息	❌ 否	-

版本号格式

正式版本:

• ✅ v1.0.0
• ✅ v2.10.102
• ✅ v1.0.1

Pre-release:

• ✅ v1.0.1-beta
• ✅ v1.0.1-rc.1
• ✅ v1.0.1-alpha

错误格式:

• ❌ v1.0（缺少补丁号）
• ❌ 1.0.0（缺少 v 前缀）
• ❌ v1.0.0.1（版本号过多）

使用场景示例

场景 1: 创建正式版本 Release

./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1" \
  -d "## 新功能
- 添加了系统更新功能
- 优化了跟单性能

## 修复
- 修复了订单状态同步问题
- 修复了账户余额显示错误"

场景 2: 创建 Pre-release（测试版本）

# 使用 --prerelease 参数，会自动拼接 -beta 后缀
./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1-beta (测试版)" \
  -d "这是 v1.0.1 的测试版本，请勿用于生产环境" \
  --prerelease
# 实际创建的 tag: v1.0.1-beta（自动拼接）

场景 3: 从文件读取 Release 描述

如果你的 Release 描述内容很长，可以保存在文件中：

# 创建描述文件
cat > release-notes.txt << 'EOF'
## 新功能
- 添加了系统更新功能
- 优化了跟单性能

## 修复
- 修复了订单状态同步问题
- 修复了账户余额显示错误

## 改进
- 提升了 API 响应速度
- 优化了数据库查询性能
EOF

# 使用文件创建 Release
./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1" \
  -f release-notes.txt

场景 4: 结合 AI 生成 Release 内容

你可以让 AI 对比代码差异生成 Release 描述，然后使用脚本发布：

# 1. AI 生成 Release 内容到文件
# 例如：对比 v1.0.0 和最新代码，生成 v1.0.1 的更新内容
# 保存到 CHANGELOG.md

# 2. 使用脚本创建 Release
./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1" \
  -f CHANGELOG.md

工作流程

脚本执行时会按以下步骤进行：

1. 验证参数

   • 检查版本号格式
   • 检查必需参数

2. 检查环境

   • 检查 git 命令
   • 检查 GitHub CLI
   • 检查 GitHub 登录状态
   • 检查未提交的更改

3. 检查 Tag

   • 检查本地是否已存在 tag
   • 检查远程是否已存在 tag
   • 如果存在，询问是否删除重建

4. 确认操作

   • 显示即将执行的操作信息
   • 等待用户确认

5. 创建 Tag

   • 基于当前 HEAD 创建 tag
   • 推送 tag 到远程

6. 创建 Release

   • 使用 GitHub CLI 创建 Release
   • 设置标题和描述
   • 标记是否为 Pre-release

7. 触发构建

   • GitHub Actions 自动检测到新 Release
   • 开始构建 Docker 镜像和更新包

注意事项

1. Tag 和 Release 的关系

• 脚本会先创建 tag，然后创建 Release
• GitHub Release 必须关联一个 tag
• 如果 tag 已存在，会询问是否删除重建

2. Pre-release 的影响

• Pre-release 不会触发 Telegram 通知
• Pre-release 不会推送到 latest Docker 标签
• Pre-release 不会被更新服务检测（除非设置 ALLOW_PRERELEASE=true）

3. GitHub Actions 触发

• GitHub Actions 监听 release: published 事件
• 只有通过脚本或 GitHub 页面创建 Release 才会触发
• 直接 git push tag 不会触发构建

4. 发布前检查清单

在创建 Release 前，建议检查：

• ✅ 代码已提交并推送
• ✅ 所有测试通过
• ✅ 版本号遵循语义化版本规范
• ✅ Release 描述内容准确完整
• ✅ 确认是否为 Pre-release

故障排除

问题 1: GitHub CLI 未安装

错误信息:

未找到 GitHub CLI (gh) 命令

解决方案:

# macOS
brew install gh

# 然后登录
gh auth login

问题 2: GitHub 未登录

错误信息:

未登录 GitHub，请先运行: gh auth login

解决方案:

gh auth login

问题 3: Tag 已存在

错误信息:

Tag v1.0.1 已存在（本地）

解决方案:

• 脚本会询问是否删除重建
• 回答 y 继续，或回答 n 取消

问题 4: 版本号格式错误

错误信息:

版本号格式不正确：v1.0

解决方案:

• 确保版本号格式为 v数字.数字.数字 或 v数字.数字.数字-后缀
• 例如：v1.0.0, v1.0.1-beta

问题 5: 未提交的更改

错误信息:

检测到未提交的更改，建议先提交或暂存

解决方案:

# 提交更改
git add .
git commit -m "准备发布 v1.0.1"

# 或暂存更改
git stash

完整示例

假设当前线上版本是 v1.0.0，要发布 v1.0.1：

# 1. 确保代码已提交
git add .
git commit -m "准备发布 v1.0.1"
git push

# 2. 使用脚本创建 Release（正式版本）
./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1" \
  -d "## 新功能
- 添加了动态更新功能
- 优化了跟单统计性能

## 修复
- 修复了订单状态同步延迟问题
- 修复了账户余额显示错误

## 改进
- 提升了 API 响应速度 30%
- 优化了数据库查询性能"

# 3. 等待 GitHub Actions 构建完成
# 可以在 GitHub Actions 页面查看构建进度

创建 Pre-release:

# 使用 --prerelease 参数，会自动拼接 -beta 后缀
./create-release.sh \
  -t v1.0.1 \
  -T "Release v1.0.1-beta (测试版)" \
  -d "这是 v1.0.1 的测试版本，包含以下更新：
- 添加了动态更新功能
- 修复了订单状态同步问题

请勿用于生产环境。" \
  --prerelease
# 实际创建的 tag: v1.0.1-beta

相关文档

• 版本号管理说明
• 动态更新技术方案
• GitHub Actions 配置