SuperAPI AI Directory
Partner中文AI newsFavorites
Skillschangelog-release-notes

changelog-release-notes

Writing & research

View repository

Updated 10-16 09:30

About this skill

Changelog Release Notes Workflow (Incremental)

Applicable Scenarios

The user has completed generating the details for a certain versionin the Chinese Changelog (e.g., # v4.2.0-rc.4), and needs the Agent to:

  1. Generate a "Change Overview" based on that incremental block and write it back to the Chinese file
  2. Translate that incremental version in its entirety into the English Changelog file

Do not generate the complete issue details from scratch for the user; by default, assume the Chinese details already exist.

Core Principle: Only Process Increments

The Changelog is maintainedincrementally: each time, only processthe one newly added version block。

Do Do Not
Only read the target version block (e.g., from # v4.2.0-rc.4 to before the next # v... ) Traverse / summarize the entire CHANGELOG file
Only insert the "Change Overview" within that version block Modify the overview or details of older versions
Only translate that version block and insert it at the top of the English file Retranslate or overwrite existing historical versions in the English file

File Conventions

Language Path Pattern Example
Chinese CHANGELOG/zh_CN/CHANGELOG-<major.minor>.md CHANGELOG/zh_CN/CHANGELOG-4.2.md
English CHANGELOG/en/CHANGELOG-<major.minor>.md CHANGELOG/en/CHANGELOG-4.2.md

The new version block is usually located at the top of the file, after <!-- NEW RELEASE NOTES ENTRY --> , inserted before the old version.

Incremental Scope Definition

"This increment" = the content in the Chinese file between the target version heading and the next version heading:

# v4.2.0-rc.4          ← 增量起点（含）
## 2026-07-16
### Changelog since v4.2.0-rc.3
...明细...
# v4.2.0-rc.3          ← 增量终点（不含）

Input Confirmation

  • Target version (required): e.g., v4.2.0-rc.4
  • Baseline version (optional): by default, read from the Changelog since ... of that block
  • Chinese / English file paths: can be inferred by major.minor

Standard Process (strictly in order, only for the incremental block)

确认目标版本
    ↓
【1】定位并只读取该版本增量块
    ↓
【2】基于该块生成「变更概述」（特性 / Bug）
    ↓
【3】将概述写回中文文件的该版本块内
    ↓
【4】仅翻译该增量块为英文
    ↓
【5】将英文增量块插入英文文件顶部（NEW RELEASE NOTES ENTRY 之后）
    ↓
完成后简要汇报：概述条数、中英文写入位置

Supports on-demand trimming:

  • "Only generate the overview" → Steps 1–3
  • "Overview already exists, only translate to English" → Steps 1, 4, 5 (translate the Chinese overview as well)

Step 2: Generate the Change Overview

Output Template (Chinese)

### 变更概述
当前版本主要变更特性如下:

**特性**
- ...

**Bug 修复**
- ...

Volume

  • Features: 5–8 items
  • Bugs: 2–4 items
  • Better fewer than piled up; the details are already below, so the overview should show only the core

Writing Style

Align with the "Change Overview" of CHANGELOG/zh_CN/CHANGELOG-4.1.md :

  • Short sentences, starting with "Support / Add / Fix", etc.
  • Do not write issue links, do not write the feat/bug/pref prefix, do not add module subheadings
  • Aimed at end users; internal optimizations do not go into the overview by default

Feature Filtering

Priority Judgment Criteria Handling
P0 Many commits with similar commit messages in the git tag comparison; or Changelog entries on the same topic are clearly concentrated Merge into 1 main highlight
P1 New user-perceivable capabilities (triggers, copy, variables, store, environment, etc.) Standalone item
P2 API/OpenAPI, channel filtering, field completion, minor OP changes Not included by default
P3 Performance, caching, monitoring, dependency upgrades Not included

Multiple entries on the same topic must be merged into 1–2 entries (summarized with "Support A, B, C").

Optional auxiliary commands (read-only, used to identify P0 topics):

git log --oneline <基线tag>..<目标tag>

Cluster by similar commit messages; topics with more commits are prioritized for the overview.

Bug filtering

Keep only high-impact items, for example:

  • Build cannot continue / cancel / retry
  • Accidental data deletion, lock not released, incorrect state
  • Core editing or trigger flows clearly abnormal

Leave minor UI issues and edge-case fixes for the details; do not include them in the overview.

Insertion location (only modify the incremental block)

# vX.Y.Z-rc.N
## YYYY-MM-DD
### Changelog since vX.Y.Z-rc.(N-1)
### 变更概述          ← 仅插这里
当前版本主要变更特性如下:
...
#### 新增             ← 用户已有明细，禁止改动

Do not modify the Added / Optimized / Fixed details already written by the user.

Step 3: Write back to the Chinese file

  • Only add the "Change Overview" within the target version block
  • Do not reorder, delete, or modify existing detail entries
  • Do not modify content from older versions
  • Keep the original file's TOC / MUNGE comment structure; if the project has a TOC generation script, do not manually edit the TOC unless the user requests it

Step 4: Translate into English (incremental block only)

Translation target = the full text of this Chinese incremental block (including the overview just inserted + the existing details).

Section title mapping

Chinese English
Added New Features
Optimized Improvements
Fixed Bug Fixes
Pipeline Pipeline
Code Repository Repository
R&D Store Store
Environment Management Environment Management
Log Service Log Service
Quality Redline Quality Gate
Permission Center Permission Center
Project Management Project Management
Scheduling Dispatch
Credential Management Credential Management
Agent Agent
Other Others
Change Overview Summary
Features Features
Bug Fixes Bug Fixes

Entry tag mapping

Chinese English
[新增] [New]
[优化] [Improved]
[修复] [Fixed]
[链接] [Link]

English overview template

### Summary
Key changes in this release:

**Features**
- ...

**Bug Fixes**
- ...

Translation requirements

  • Keep issue links, version numbers, and date structures unchanged
  • Product proper nouns may be retained: PAC, TAPD, CodeCC, BK-CI, etc.
  • "创作流" is translated as Creation Flow
  • Word order should be natural; avoid word-for-word literal translation; consistent with CHANGELOG/en/CHANGELOG-*.md 's existing writing style
  • English overview entries correspond one-to-one with the Chinese overview, with the same number of entries

Step 5: Write to the English file (incremental insertion)

  • Insert the complete new version block at the top of the English file (<!-- NEW RELEASE NOTES ENTRY --> after, before the previous version)
  • If the English file does not yet have this version, add the entire block
  • If this version already exists: ask the user first; do not overwrite by default
  • Do not rewrite the English content of older versions

Trigger phrase examples

  • "According to changelog-release-notes, handle the v4.2.0-rc.4 increment"
  • "The Chinese rc.4 has been written; add the overview and sync to English"
  • "Only generate the overview; do not write English yet"
  • "The overview already exists; only translate to English"

Completion checklist

  • Only the target version incremental block was read and written; no historical versions were modified
  • Chinese only added "Change Overview"; details untouched
  • 5–8 features, 2–4 bugs, no issue links
  • English only added the corresponding version; historical English unchanged
  • Sections / labels converted according to the mapping table
  • Links and version numbers not lost
  • Chinese and English overview entries count consistent

Note

  • Do not create a git commit by default; unless the user explicitly requests a commit
  • Do not proactively modify the overview or translation of historical versions
  • For entries you are unsure whether to include in the overview, do not include them by default; you may list "optional additions" in one sentence at the end of the reply for the user to decide