claude-relay-service/.github/AUTO_RELEASE_GUIDE.md

自动版本发布指南

📋 概述

本项目配置了自动版本发布功能，每次推送到 main 分支时会自动递增版本号并创建 GitHub Release。

🚀 工作原理

自动版本递增规则

• 版本格式: v<major>.<minor>.<patch> （例如: v1.0.2）
• 递增规则: 每次推送到 main 分支，自动递增 patch 版本号
  • v1.0.1 → v1.0.2
  • v1.0.9 → v1.0.10
  • v1.0.99 → v1.0.100

触发条件

当满足以下条件时，会自动创建新版本：

1. 推送到 main 分支
2. 有实际的代码变更（不包括纯文档更新）
3. 自上次发布以来有新的提交

📝 使用方法

1. 常规开发流程

# 在 dev 分支开发
git checkout dev
# ... 进行开发 ...
git add .
git commit -m "feat: 添加新功能"
git push origin dev

# 合并到 main 分支
git checkout main
git merge dev
git push origin main  # 这会触发自动发布

2. 跳过自动发布

如果你的提交不想触发自动发布，在 commit 消息中添加 [skip ci]：

git commit -m "docs: 更新文档 [skip ci]"

3. 手动控制版本号

如果需要发布大版本或中版本更新：

# 大版本更新 (1.0.x → 2.0.0)
git tag -a v2.0.0 -m "Major release v2.0.0"
git push origin v2.0.0

# 中版本更新 (1.0.x → 1.1.0)
git tag -a v1.1.0 -m "Minor release v1.1.0"
git push origin v1.1.0

🔧 配置说明

工作流文件

• 位置: .github/workflows/auto-release.yml
• 功能:
  • 获取最新版本标签
  • 计算下一个版本号
  • 生成 changelog
  • 创建 GitHub Release
  • 更新 CHANGELOG.md 文件

Changelog 生成

使用 git-cliff 自动生成更新日志：

• 配置文件: .github/cliff.toml
• 提交规范: 遵循 Conventional Commits
  • feat: 新功能
  • fix: Bug 修复
  • docs: 文档更新
  • chore: 其他变更
  • refactor: 代码重构
  • perf: 性能优化

📊 查看发布历史

1. GitHub Releases 页面:

   • 访问 https://github.com/<owner>/<repo>/releases
   • 查看所有发布版本和更新内容

2. CHANGELOG.md:

   • 项目根目录的 CHANGELOG.md 文件
   • 包含完整的版本历史

❓ 常见问题

Q: 如何查看当前版本？

# 查看最新标签
git describe --tags --abbrev=0

# 查看所有标签
git tag -l

Q: 自动发布失败怎么办？

1. 检查 GitHub Actions 日志
2. 确认是否有权限创建标签和发布
3. 检查是否有语法错误

Q: 如何回滚版本？

自动发布只是创建标签和 Release，不会影响代码：

# 回滚到特定版本
git checkout v1.0.1

# 或者使用 Docker 镜像的特定版本
docker pull weishaw/claude-relay-service:v1.0.1

Q: 如何修改版本递增规则？

编辑 .github/workflows/auto-release.yml 中的版本计算逻辑：

# 当前是递增 patch 版本
NEW_PATCH=$((PATCH + 1))

# 可以改为递增 minor 版本
NEW_MINOR=$((MINOR + 1))
NEW_PATCH=0

🔗 相关链接

• GitHub Actions 工作流使用指南
• Docker Hub 设置指南
• Git Cliff 配置文档