name: release-version description: 在发布新版本时使用 - 指导版本更新、变更日志生成、提交分组、标签和GitHub CI跟踪。触发词包括“发布新版本”、“release”、“发版”或版本发布请求。

发布版本工作流程

概述

MioSub的完整发布工作流程，处理版本更新、从git历史生成变更日志、提交分组、标签创建和GitHub CI监控。

何时使用

用户说“发布新版本”、“release”、“发版”
用户请求版本发布
在向GitHub发布新版本之前

工作流程步骤

步骤0：预检问题

询问用户：

版本号 - 发布什么版本？（例如：2.12.0）
预发布？ - 这是预发布版本吗？（影响GitHub发布设置）

步骤1：检查和提交未提交的更改

运行 git status 检查未提交的更改
如果有更改：
- 按主题/功能分析更改
- 将相关更改分组在一起
- 为每个主题组创建单独的提交
- 使用常规提交消息（feat:、fix:、chore:等）

步骤2：生成变更日志

找到前一个版本标签：
```
git describe --tags --abbrev=0
```
获取自上次标签以来的所有提交：
```
git log <previous-tag>..HEAD --oneline
```
读取每个提交的详细信息以分类：
- 新功能 - 新功能（feat:）
- 修复 - Bug修复（fix:）
- 重构 - 代码改进（refactor:）
- 杂项 - 维护任务（chore:）
- 文档 - 文档更新（docs:）
- 性能 - 性能改进（perf:）
从变更日志中排除（与用户无关的内部/基础设施更改）：
- 错误跟踪更改（Sentry集成、错误报告）
- 分析/遥测服务修改
- 内部监控或日志基础设施
更新文档站点的变更日志文件（双语）：

英文 (docs/content/docs/en/changelog.mdx):
- 在前置内容和介绍段落之后添加新版本部分
- 格式：## [X.X.X] - YYYY-MM-DD（无’v’前缀）
- 按类别分组条目（保持变更日志格式）
- 使用英文描述
中文 (docs/content/docs/zh/changelog.mdx):
- 镜像与英文相同的结构
- 将所有描述翻译成中文
- 使用中文类别名称：新功能、修复、重构、杂项、文档、性能
更新 package.json：
- 将 "version": "X.X.X" 更改为新版本（无’v’前缀）

步骤3：提交发布文件

git add docs/content/docs/en/changelog.mdx docs/content/docs/zh/changelog.mdx package.json
git commit -m "Release vX.X.X"

注意：提交消息使用’v’前缀，但文件中的版本字符串不使用。

步骤4：标签和推送

git tag vX.X.X
git push origin main
git push origin vX.X.X

注意：标签使用’v’前缀（例如：v2.12.0）。

步骤5：监控GitHub CI

跟踪GitHub Actions工作流程：

gh run list --workflow=release.yml --limit=1
gh run watch <run-id>

向用户报告构建状态：
- 成功：提供发布URL
- 失败：显示错误详细信息

快速参考

步骤	命令	目的
检查状态	`git status`	查找未提交的更改
前一个标签	`git describe --tags --abbrev=0`	获取上次发布标签
提交日志	`git log <tag>..HEAD --oneline`	列出自发布以来的更改
创建标签	`git tag vX.X.X`	创建版本标签
推送标签	`git push origin vX.X.X`	触发CI构建
监控CI	`gh run watch`	监控构建进度

版本格式规则

位置	格式	示例
Git标签	带’v’前缀	`v2.12.0`
提交消息	带’v’前缀	`Release v2.12.0`
changelog.mdx (中/英)	无’v’前缀	`## [2.12.0] - 2026-01-06`
package.json	无’v’前缀	`"version": "2.12.0"`

变更日志文件位置

语言	路径
英文	`docs/content/docs/en/changelog.mdx`
中文	`docs/content/docs/zh/changelog.mdx`

CHANGELOG格式（英文）

## [X.X.X] - YYYY-MM-DD

### Features

- **Component**: Description of new feature.

### Fixes

- **Component**: Description of bug fix.

### Refactor

- **Component**: Description of refactoring.

### Chore

- **Component**: Maintenance description.

CHANGELOG格式（中文）

## [X.X.X] - YYYY-MM-DD

### 新功能

- **组件名**: 新功能描述。

### 修复

- **组件名**: Bug修复描述。

### 重构

- **组件名**: 重构描述。

### 杂项

- **组件名**: 维护工作描述。

类别名称映射

英文	中文
Features	新功能
Fixes	修复
Refactor	重构
Chore	杂项
Documentation	文档
Performance	性能
Highlights	亮点
Improvements	改进
Other Changes	其他变更

常见错误

错误	修复
忘记推送标签	CI仅在标签推送时触发，而不是提交推送
package.json中的错误版本	版本必须与标签匹配（无’v’前缀）
变更日志位置错误	新版本应放在前置内容之后、之前版本之前
未分组提交	相关更改应在一个提交中，以便历史更清晰
不一致的’v’前缀	标签和提交使用’v’，文件不使用
缺少中文翻译	英文和中文变更日志文件必须同时更新
不匹配的类别翻译	使用类别名称映射表以确保一致性

预发布处理

对于预发布版本：

使用版本格式：X.X.X-beta.1、X.X.X-rc.1
标签格式：vX.X.X-beta.1
注意：当前CI工作流程设置 prerelease: false - 可能需要在GitHub发布中手动调整