| name | changelog-release-notes |
| description | BK-CI 发版 Changelog 增量处理:仅针对本次新增版本块生成「变更概述」并写回中文文件, 再将该增量版本翻译到英文 CHANGELOG。当用户提到发版摘要、变更概述、CHANGELOG 翻译、 中英文 changelog、vX.Y.Z-rc、补充概述、同步英文日志时使用。 |
Changelog 发版说明工作流(增量)
适用场景
用户已完成中文 Changelog 某一版本的明细生成(如 # v4.2.0-rc.4),需要 Agent:
- 基于该增量块生成「变更概述」,并写回中文文件
- 将该增量版本整段翻译到英文 Changelog 文件
不要替用户从零生成完整 issue 明细;默认假设中文明细已存在。
核心原则:只处理增量
Changelog 是增量维护的:每次只处理当前新增的那一个版本块。
| 要做 | 不要做 |
|---|
只读目标版本块(如 # v4.2.0-rc.4 到下一个 # v... 之前) | 遍历 / 总结整个 CHANGELOG 文件 |
| 只在该版本块内插入「变更概述」 | 修改更旧版本的概述或明细 |
| 只把该版本块翻译并插入英文文件顶部 | 重译或覆盖英文文件里已有历史版本 |
文件约定
| 语言 | 路径模式 | 示例 |
|---|
| 中文 | CHANGELOG/zh_CN/CHANGELOG-<major.minor>.md | CHANGELOG/zh_CN/CHANGELOG-4.2.md |
| 英文 | CHANGELOG/en/CHANGELOG-<major.minor>.md | CHANGELOG/en/CHANGELOG-4.2.md |
新版本块通常位于文件顶部 <!-- NEW RELEASE NOTES ENTRY --> 之后,插在旧版本之前。
增量范围定义
「本次增量」= 中文文件中目标版本标题到下一版本标题之间的内容:
# v4.2.0-rc.4 ← 增量起点(含)
## 2026-07-16
### Changelog since v4.2.0-rc.3
...明细...
# v4.2.0-rc.3 ← 增量终点(不含)
输入确认
- 目标版本(必填):如
v4.2.0-rc.4
- 基线版本(可选):默认从该块的
Changelog since ... 读取
- 中文 / 英文文件路径:可按 major.minor 推断
标准流程(严格按序,仅针对增量块)
确认目标版本
↓
【1】定位并只读取该版本增量块
↓
【2】基于该块生成「变更概述」(特性 / Bug)
↓
【3】将概述写回中文文件的该版本块内
↓
【4】仅翻译该增量块为英文
↓
【5】将英文增量块插入英文文件顶部(NEW RELEASE NOTES ENTRY 之后)
↓
完成后简要汇报:概述条数、中英文写入位置
支持按需裁剪:
- 「只生成概述」→ 步骤 1~3
- 「概述已有,只翻译英文」→ 步骤 1、4、5(中文概述一并译出)
步骤2:生成变更概述
输出模板(中文)
### 变更概述
当前版本主要变更特性如下:
**特性**
- ...
**Bug 修复**
- ...
体量
- 特性:5~8 条
- Bug:2~4 条
- 宁可少,不要堆;下方已有明细,概述只展示核心
文风
对齐 CHANGELOG/zh_CN/CHANGELOG-4.1.md 的「变更概述」:
- 短句,以「支持 / 增加 / 修复」等开头
- 不写 issue 链接、不写
feat/bug/pref 前缀、不加模块小标题
- 面向终端用户;内部优化默认不进概述
特性筛选
| 优先级 | 判断标准 | 处理 |
|---|
| P0 | git tag 对比中相近 commit message 提交多;或同主题 Changelog 条目明显集中 | 合并成 1 条主推 |
| P1 | 用户可感知的新能力(触发、复制、变量、商店、环境等) | 单独成条 |
| P2 | API/OpenAPI、渠道过滤、字段补齐、OP 小改 | 默认不进 |
| P3 | 性能、缓存、监控、依赖升级 | 不进 |
同一主题多条必须合并为 1~2 条(用「支持 A、B、C」收束)。
可选辅助命令(只读,用于识别 P0 主题):
git log --oneline <基线tag>..<目标tag>
按相近 commit message 聚类,提交多的主题优先进入概述。
Bug 筛选
只保留高影响项,例如:
- 构建无法继续 / 取消 / 重试
- 数据误删、锁未释放、状态错误
- 核心编辑或触发流程明显异常
UI 小问题、边缘场景修复留给明细,不进概述。
插入位置(仅改增量块)
# vX.Y.Z-rc.N
## YYYY-MM-DD
### Changelog since vX.Y.Z-rc.(N-1)
### 变更概述 ← 仅插这里
当前版本主要变更特性如下:
...
#### 新增 ← 用户已有明细,禁止改动
不要改动用户已写好的新增 / 优化 / 修复明细。
步骤3:写回中文文件
- 仅在目标版本块内补充「变更概述」
- 不重排、不删改已有明细条目
- 不修改更旧版本内容
- 保持原文件 TOC / MUNGE 注释结构;若项目有 TOC 生成脚本则不要手改 TOC,除非用户要求
步骤4:翻译为英文(仅增量块)
翻译对象 = 本次中文增量块全文(含刚插入的概述 + 原有明细)。
章节标题映射
| 中文 | 英文 |
|---|
| 新增 | New Features |
| 优化 | Improvements |
| 修复 | Bug Fixes |
| 流水线 | Pipeline |
| 代码库 | Repository |
| 研发商店 | Store |
| 环境管理 | Environment Management |
| 日志服务 | Log Service |
| 质量红线 | Quality Gate |
| 权限中心 | Permission Center |
| 项目管理 | Project Management |
| 调度 | Dispatch |
| 凭证管理 | Credential Management |
| Agent | Agent |
| 其他 | Others |
| 变更概述 | Summary |
| 特性 | Features |
| Bug 修复 | Bug Fixes |
条目标签映射
| 中文 | 英文 |
|---|
[新增] | [New] |
[优化] | [Improved] |
[修复] | [Fixed] |
[链接] | [Link] |
英文概述模板
### Summary
Key changes in this release:
**Features**
- ...
**Bug Fixes**
- ...
翻译要求
- 保留 issue 链接、版本号、日期结构不变
- 产品专有名词可保留:PAC、TAPD、CodeCC、BK-CI 等
- 「创作流」译为
Creation Flow
- 语序自然,避免逐字硬翻;与
CHANGELOG/en/CHANGELOG-*.md 既有文风一致
- 英文概述条目与中文概述一一对应,条数一致
步骤5:写入英文文件(增量插入)
- 将完整新版本块插入英文文件顶部(
<!-- NEW RELEASE NOTES ENTRY --> 之后、上一版本之前)
- 若英文文件尚无该版本,则新增整块
- 若已存在该版本:先询问用户,默认不覆盖
- 不要改写更旧版本的英文内容
触发话术示例
- 「按 changelog-release-notes,处理 v4.2.0-rc.4 增量」
- 「中文 rc.4 已写好,补概述并同步英文」
- 「只生成概述,先别写英文」
- 「概述已有,只翻译英文」
完成检查清单
注意
- 默认不创建 git commit;除非用户明确要求提交
- 不要主动修改历史版本的概述或翻译
- 对拿不准是否进入概述的条目,默认不进;可在回复末尾用一句话列出「可选补充项」供用户决定