Skip to content

ai: add release notes SKILL #22712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Oreoxmt wants to merge 1 commit into
base: master
Choose a base branch
from
Open

ai: add release notes SKILL #22712

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 160 additions & 0 deletions .ai/skills/write-review-translate-release-notes/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
---
name: release-notes
description: Review, revise, write, and translate TiDB release notes for the Compatibility changes, Improvements, and Bug fixes sections in English and Chinese. Use this skill when working with release note entries, aligning English and Chinese content, auditing `release-X.X.X.md` files, or editing files under `docs/releases/` or `docs-cn/releases/`.
---

# TiDB Release Notes

This skill enforces the style used in published release notes in `docs/releases/` (English) and `docs-cn/releases/` (Chinese) for v6.1.0 and later.

## When to use this skill

Use this skill when the task involves any of the following:

- **Writing a new entry** based on a GitHub PR or issue description
- **Reviewing or revising** an existing English or Chinese release note entry or section (Compatibility changes, Improvements, or Bug fixes), such as correcting the opening verb, tightening the description, or fixing style issues
- **Translating** an entry between English and Chinese, including updating document anchor suffixes and verifying bilingual alignment

This skill applies to the three recurring sections in every `release-X.X.X.md` file: Compatibility changes, Improvements, and Bug fixes.

## Which reference file to load

Read only what is necessary for the task.

- Compatibility changes (upgrade note blocks, behavior-change paragraphs, system-variable tables, config-parameter tables, anchor suffix conventions): read [references/compatibility-changes.md](references/compatibility-changes.md)
- Improvement entries (opening verbs, English and Chinese patterns, examples): read [references/improvements.md](references/improvements.md)
- Bug-fix entries (fix templates, anti-patterns, English and Chinese patterns, examples): read [references/bug-fixes.md](references/bug-fixes.md)
- Translating between English and Chinese, checking bilingual alignment, or auditing paired files: read [references/bilingual-alignment.md](references/bilingual-alignment.md)

A Chinese-only bug-fix revision does not require the compatibility-changes file.

## File-level structure

### English file (`docs/releases/release-X.X.X.md`)

```markdown
---
title: TiDB X.X.X Release Notes
summary: Learn about the compatibility changes, improvements, and bug fixes in TiDB X.X.X.
---

# TiDB X.X.X Release Notes

Release date: Month DD, YYYY

TiDB version: X.X.X

Quick access: [Quick start](https://docs.pingcap.com/tidb/vX.X/quick-start-with-tidb) | [Production deployment](https://docs.pingcap.com/tidb/vX.X/production-deployment-using-tiup)
```

The `summary` value lists the sections actually present in the file, in the same order as the level-2 headings. For example, if the file includes New features, Compatibility changes, Improvements, and Bug fixes, the summary reads: `Learn about the new features, compatibility changes, improvements, and bug fixes in TiDB X.X.X.` If a section is absent, omit it from the summary.

### Chinese file (`docs-cn/releases/release-X.X.X.md`)

```markdown
---
title: TiDB X.X.X Release Notes
summary: 了解 TiDB X.X.X 版本的兼容性变更、改进提升，以及错误修复。
---

# TiDB X.X.X Release Notes

发版日期：YYYY 年 M 月 D 日

TiDB 版本：X.X.X

试用链接：[快速体验](https://docs.pingcap.com/zh/tidb/vX.X/quick-start-with-tidb) | [生产部署](https://docs.pingcap.com/zh/tidb/vX.X/production-deployment-using-tiup)
```

### Section heading mapping

| English | Chinese |
|---------|---------|
| `## Compatibility changes` | `## 兼容性变更` |
| `### Behavior changes` | `### 行为变更` |
| `### System variables` | `### 系统变量` |
| `### Configuration file parameters` | `### 配置文件参数` |
| `## Deprecated features` | `## 废弃功能` |
| `## Improvements` | `## 改进提升` |
| `## Bug fixes` | `## 错误修复` |
| `## Performance test` | `## 性能测试` |
| `## Contributors` | `## 贡献者` |

## Rules that apply to every entry

These rules apply to both Improvements and Bug fixes in both languages. The reference files assume these conventions.

### No trailing period

Entries do not end with `.` (English) or `。` (Chinese).

### Write from the user's perspective

Describe what the user observes, not what the code does.

- Bug fixes: start from the GitHub issue description (user-facing symptoms). Avoid exposing internal function or variable names.
- Improvements: use the GitHub PR as a reference, but reframe the entry in terms of user benefit (performance, stability, or capability).
- A complete bug fix describes both the trigger condition and the observed impact. A complete improvement explains what changed and why it benefits the user.

### Inline code

Use backticks for:

- Variable names: `` `tidb_mem_quota_analyze` ``
- Config parameters: `` `raftstore.inspect-interval` ``, command-line flags: `` `--ignore-stats` ``
- SQL keywords in ALL CAPS: `` `HAVING` ``, `` `COUNT DISTINCT` ``, `` `ORDER BY` ``
- SQL functions in ALL CAPS with parentheses: `` `DATE()` ``, `` `STR_TO_DATE()` ``, `` `COUNT()` ``
- Exact error message strings: `` `Can't find a proper physical plan for this query` ``
- Operator or plan names: `` `IndexHashJoin` ``, `` `MPP` ``
- Literal values, ports, sizes: `` `8123` ``, `` `"8KiB"` ``, `` `false` ``

Do not wrap product or component names in prose (TiDB, TiKV, PD, TiFlash, TiCDC), or generic nouns such as "query," "table," or "index," unless referring to a specific named object.

### Entry suffix

Each improvement and bug-fix entry ends with issue link(s) and contributor, in the following format:

Check failure on line 115 in .ai/skills/write-review-translate-release-notes/SKILL.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.OptionalPlurals] Don't use plurals in parentheses such as in 'link(s)'.

Raw Output:
{"message": "[PingCAP.OptionalPlurals] Don't use plurals in parentheses such as in 'link(s)'.", "location": {"path": ".ai/skills/write-review-translate-release-notes/SKILL.md", "range": {"start": {"line": 115, "column": 52}}}, "severity": "ERROR"}

```
[#NNNNN](https://github.com/org/repo/issues/NNNNN) @[contributor](https://github.com/contributor)
```

For multiple issues in one entry: `[#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) [#MMMMM](https://github.com/pingcap/tidb/issues/MMMMM) @[contributor](https://github.com/contributor)`

## Quick reference

### English bug-fix templates

```
- Fix the issue that [subject] [verb phrase]
- Fix the issue that [subject] might [crash/panic/get stuck/return incorrect results]
- Fix the issue of [noun phrase] that occurs when [condition]
- Fix the [incorrect/inaccurate] [noun]
- Fix a [rare/potential] issue that [description]
- Fix the potential [panic/crash] that occurs when [condition]
- Fix the panic issue caused by [X]
```

### Chinese bug-fix templates

```
- 修复 [X] 的问题
- 修复 [X] 可能 [崩溃/panic/卡住/报错/返回错误结果] 的问题
- 修复 [X] 导致 [Y] 的问题
```

### Improvement opening verbs

| English | Chinese |
|---------|---------|
| Support, Add, Optimize, Improve, Avoid, Enhance, Mitigate, Accelerate, Remove, Increase | 支持、新增、优化、提升、避免、改进、引入、增加 |

### Compatibility change-type vocabulary

| English | Chinese |
|---------|---------|
| `Newly added` | `新增` |
| `Modified` | `修改` |
| `Deprecated` | `废弃` |
| `Deleted` | `删除` |

Component names in section headers are identical in English and Chinese: `TiDB`, `TiKV`, `PD`, `TiFlash`, `TiDB Lightning`, `BR`, `TiCDC`.
98 changes: 98 additions & 0 deletions .ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Bilingual alignment and translation

Use this file for checking English/Chinese alignment of a paired release note file, translating entries in either direction, or auditing alignment by issue number. The cross-cutting rules in SKILL.md apply here too.

## Contents

- Alignment checklist
- Revision workflow
- English to Chinese translation
- Chinese to English translation

## Alignment checklist

### Must-be-identical items (no translation needed)

- Issue/PR numbers and URLs: `[#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN)`
- Contributor handles and URLs: `@[contributor](https://github.com/contributor)`
- Inline code spans: `` `variable_name` ``, `` `COMMAND` ``, `` `--flag` ``
- Component names in section headers: `TiDB`, `TiKV`, `PD`, `TiFlash`, `BR`, `TiCDC`, `TiDB Lightning`
- Version numbers: `v7.5.0`, `v8.1.0`

### Anchor suffix convention

- English anchor for new variables/parameters: `#var_name-new-in-vXYZ`
- Chinese anchor for new variables/parameters: `#var_name-从-vXYZ-版本开始引入`
- Both link to the same doc page; only the anchor fragment differs
- Pre-existing variables (not new in this version): no suffix in either language — just `#var_name`

Check failure on line 27 in .ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.EmDash] Don't put a space before or after a dash.

Raw Output:
{"message": "[PingCAP.EmDash] Don't put a space before or after a dash.", "location": {"path": ".ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md", "range": {"start": {"line": 27, "column": 81}}}, "severity": "ERROR"}

### Section presence parity

- Each English section must have an exact Chinese counterpart.
- Example: If the English file has `### Behavior changes`, the Chinese file must have `### 行为变更`.
- Missing sections are considered defects. See SKILL.md for section heading mappings.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Use active voice to improve clarity and follow the style guide's preference for direct instructions.

Suggested change
- Missing sections are considered defects. See SKILL.md for section heading mappings.
- Treat missing sections as defects. See SKILL.md for section heading mappings.
References
  1. Avoid passive voice overuse. (link)


### Table parity

- English and Chinese compatibility tables must have:
- Same number of rows
- Same row order
- Same variable/parameter names
- Matching change-type translations (`Newly added` ↔ `新增`, `Modified` ↔ `修改`, etc.)

Check failure on line 41 in .ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[PingCAP.Latin] Use 'such as' instead of 'etc.'.

Raw Output:
{"message": "[PingCAP.Latin] Use 'such as' instead of 'etc.'.", "location": {"path": ".ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md", "range": {"start": {"line": 41, "column": 81}}}, "severity": "ERROR"}

### Note block punctuation

- English: `> **Note:**` (ASCII colon, no space after `**`)
- Chinese: `> **注意：**` (full-width colon `：`, inside the bold span)

### Contributors section

- English first-time contributor tag: `- [handle](url) (First-time contributor)`
- Chinese first-time contributor tag: `- [handle](url)（首次贡献者）` (full-width parentheses)

## Revision workflow

### Reviewing an existing entry

1. Identify the section (Compatibility changes, Improvements, or Bug fixes)
2. Check the opening pattern against section rules
3. Verify trailing punctuation (no `.` in English; no `。` in Chinese)
4. Verify inline code spans for all technical terms: variables, configs, SQL keywords/functions, error messages
5. Verify the issue link and contributor link at the end of the line
6. For Chinese entries: verify `修复` as the opening verb for bug fixes, or an approved opening verb for improvements

### Writing a new entry from a PR or issue description

1. Read the PR title and description. For bug fixes, prioritize the linked GitHub Issue (user-facing symptoms) over the PR diff (code changes)
2. Identify the component (TiDB, TiKV, PD, TiFlash, BR, TiCDC, TiDB Lightning)
3. Draft the English entry:
- Bug fix: `Fix the issue that [concise repro condition and observed symptom] [#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) @[contributor](https://github.com/contributor)`
- Improvement: `[Action verb] [what was improved, added, or supported] [#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) @[contributor](https://github.com/contributor)`
4. Draft the Chinese entry with the matching pattern
5. Verify issue numbers match exactly between English and Chinese
6. Verify anchor suffix format if doc links are included
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Use active voice and address the user directly as 'you' to maintain consistency with the style guide.

Suggested change
6. Verify anchor suffix format if doc links are included
6. Verify the anchor suffix format if you include documentation links
References
  1. Write in second person ('you') when addressing users. (link)
  2. Avoid passive voice overuse. (link)


## English to Chinese translation

1. Identify if the entry is a bug fix or improvement
2. Map the opening verb/phrase:
- `Fix the issue that X` → `修复 [X 的中文表述] 的问题`
- `Fix the issue that X might Y` → `修复 [X] 可能 [Y] 的问题`
- `Fix the issue of X that occurs when Y` → `修复 [Y] 时 [X] 的问题`
- `Improve/Optimize/Support/Add/Avoid X` → `优化/支持/新增/避免 [X 的中文表述]`
3. Keep all inline code unchanged
4. Keep all issue links and contributor links unchanged
5. Update doc anchor suffixes: `-new-in-vXYZ` → `-从-vXYZ-版本开始引入`
6. Do not add a trailing period

## Chinese to English translation

1. Identify the pattern:
- `修复 [X] 的问题` → `Fix the issue that [X in English]`
- `修复 [X] 可能 [Y] 的问题` → `Fix the issue that [X in English] might [Y in English]`
- `修复 [X] 导致 [Y] 的问题` → `Fix the issue that [X] causes [Y]`
- Chinese improvement verb maps to the corresponding English action verb (see improvements.md)
2. Keep all inline code unchanged
3. Keep all issue links and contributor links unchanged
4. Update doc anchor suffixes: `-从-vXYZ-版本开始引入` → `-new-in-vXYZ`
5. Do not add a trailing period
94 changes: 94 additions & 0 deletions .ai/skills/write-review-translate-release-notes/references/bug-fixes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Bug fixes

Rules for the `## Bug fixes` / `## 错误修复` section. The cross-cutting rules in SKILL.md (no trailing period, user perspective, inline-code conventions, and entry suffix) also apply here.

The section structure is identical to Improvements: use `+` for component groups and `-` for entries, with tools nested one level deeper under `+ Tools`. See [improvements.md](improvements.md) for the structure skeleton.

## Contents

- English style rules and templates
- Handling non-deterministic failures (`might` vs `potential`)
- Chinese style rules and templates
- Anti-patterns for both languages

## English style rules

Lead with a fix verb phrase. The accepted patterns, listed roughly by frequency in published v6.1+ notes:
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Rephrase to use active voice for a more direct and professional tone.

Suggested change
Lead with a fix verb phrase. The accepted patterns, listed roughly by frequency in published v6.1+ notes:
Lead with a fix verb phrase. Use the following accepted patterns, which are listed roughly by frequency in published v6.1+ notes:
References
  1. Avoid passive voice overuse. (link)


- `Fix the issue that [subject] [verb phrase]` (dominant modern pattern)
- `Fix the issue of [noun phrase] that occurs when/during [condition]` (result-first phrasing)
- `Fix the issue of [noun phrase]` (noun-centric, no trigger clause)
- `Fix the [incorrect/inaccurate] [noun]` (standalone, for example, `Fix the incorrect error message ...`)
- `Fix a [rare/potential] issue that [description]` (rare or non-deterministic bugs)
- `Fix the potential/occasional [panic/crash] that occurs when [condition]` (specific crash scenarios)
- `Fix the panic issue caused by [X]` (panic identified by cause)

A complete entry should include three elements: the trigger condition (when it happens), the observed impact (what the user sees), and optionally a workaround.

Wrap exact error messages in backticks: `Fix the issue that TiDB Lightning reports` `` `no database selected` `` `during data import`.

### Handling non-deterministic failures

Both `might` and `potential` are acceptable. Use them as follows:

- Use `might` as an inline modal verb: `Fix the issue that TiDB might crash when ...`
- Use `potential` as an adjective before a noun: `Fix the potential panic that occurs when ...`
- Do not use `may` or `could`.

### English examples (from v7.5.0 and v8.1.0)

```
- Fix the issue that executing SQL statements containing tables with multi-valued indexes might return the `Can't find a proper physical plan for this query` error [#49438](...) @[qw4990](https://github.com/qw4990)
- Fix the issue that automatic statistics collection gets stuck after an OOM error occurs [#51993](...) @[hi-rustin](https://github.com/hi-rustin)
- Fix the issue that after using BR to restore a table that has no statistics, the statistics health of that table is still 100% [#29769](...) @[winoros](https://github.com/winoros)
- Fix the issue that TiDB might crash when `tidb_mem_quota_analyze` is enabled and the memory used by updating statistics exceeds the limit [#52601](...) @[hawkingrei](https://github.com/hawkingrei)
- Fix the incorrect error message displayed when an invalid default value is specified for a column [#51592](...) @[danqixu](https://github.com/danqixu)
- Fix a rare issue that special event timing might cause the data loss in log backup [#16739](...) @[YuJuncen](https://github.com/YuJuncen)
- Fix the panic issue caused by `GetAdditionalInfo` [#8079](...) @[HuSharp](https://github.com/HuSharp)
- Fix the issue that inactive Write Ahead Logs (WALs) in RocksDB might corrupt data [#16705](...) @[Connor1996](https://github.com/Connor1996)
- Fix the issue that the MySQL compression protocol cannot handle large loads of data (>=16M) [#47152](...) [#47157](...) [#47161](...) @[dveeden](https://github.com/dveeden)
```

### English anti-patterns

| Incorrect | Correct |
|-----------|---------|
| `Fixed the issue that ...` (past tense) | `Fix the issue that ...` (imperative) |
| `Fixes an issue where ...` | `Fix the issue that ...` |
| `Fix the issue where ...` | `Fix the issue that ...` (use `that`, not `where`) |
| `Fix the issue that ... may ...` | Use `might` or `potential` |
| Entry ends with `.` | Remove the period |
| `Fix npe in executeTS` (internal name) | Rewrite to user-observable behavior: `Fix the potential panic issue that occurs when running table scan tasks` |
| `The issue of X causing Y is fixed` | `Fix the issue that X causes Y` |

## Chinese style rules

Lead with `修复` for most entries. The standard templates are:

* `修复 [X] 的问题` (most common)
* `修复 [X] 可能 [崩溃/panic/卡住/报错] 的问题` (non-deterministic failures)
* `修复 [X] 导致 [Y] 的问题` (cause-effect issues)
* `禁止 [X]` (used when the fix introduces a restriction rather than a repair; rare)
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Use active voice in the parenthetical instruction to follow the style guide.

Suggested change
* `禁止 [X]` (used when the fix introduces a restriction rather than a repair; rare)
* 禁止 [X] (Use this when the fix introduces a restriction rather than a repair; rare)
References
  1. Avoid passive voice overuse. (link)


Close the description clause with `的问题`. Use `可能` for non-deterministic failures, consistent with the English use of `might`. Do not add `。` at the end.

### Chinese examples (from v7.5.0 and v8.1.0)

```
- 修复 Sort 算子在落盘过程中可能导致 TiDB 崩溃的问题 [#47538](...) @[windtalker](https://github.com/windtalker)
- 修复 HashJoin 算子 Probe 时无法复用 chunk 的问题 [#48082](...) @[wshwsh12](https://github.com/wshwsh12)
- 修复 `COALESCE()` 函数对于 `DATE` 类型参数返回结果类型不正确的问题 [#46475](...) @[xzhangxian1008](https://github.com/xzhangxian1008)
- 修复 `client-go` 中 `batch-client` panic 的问题 [#47691](...) @[crazycs520](https://github.com/crazycs520)
- 修复 MySQL 压缩协议无法处理超大负载数据 (>= 16M) 的问题 [#47152](...) [#47157](...) [#47161](...) @[dveeden](https://github.com/dveeden)
- 禁止非整型聚簇索引进行 split table 操作 [#47350](...) @[tangenta](https://github.com/tangenta)
- 修复采用自适应同步部署模式 (DR Auto-Sync) 的集群在 Placement Rule 的配置较复杂时，`canSync` 和 `hasMajority` 可能计算错误的问题 [#7201](...) @[disksing](https://github.com/disksing)
```

### Chinese anti-patterns

| Incorrect | Correct |
|-----------|---------|
| `修复了 ...` (with `了`) | `修复 ...` (remove `了`) |
| Entry ends with `。` | Remove `。` |
| `修复 ... 的 bug` | `修复 ... 的问题` |
| `解决了 ...` | `修复 ...` |
Loading
Loading