Skip to content

ai: add feature-description reference for release notes skill #23052

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

Merged
ti-chi-bot merged 3 commits into from
Jun 12, 2026
Merged

ai: add feature-description reference for release notes skill #23052

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
946b08f
add skills for writing feature descriptions
qiancai Jun 11, 2026
28412f2
Update feature-description.md
qiancai Jun 11, 2026
a2c9a8e
Merge branch 'master' into skill-feature-description
qiancai Jun 12, 2026
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
2 changes: 1 addition & 1 deletion .ai/AI-README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui
- `.ai/skills/review-doc-pr/`: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and style
- `.ai/skills/create-or-update-zh-translation-pr/`: create a new docs translation PR or update an existing one by combining repo-local scripts with minimal-edit translation rules and incremental source-diff handling
- `.ai/skills/writing-doc-summaries/`: write or update the `summary` front matter field in a document following the repo's 115-145 character SEO-friendly sentence rules
- `.ai/skills/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
- `.ai/skills/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Feature details/Features, Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
- `.ai/skills/docs-pr-metadata-guard/`: guard PR template structure when creating or editing pull requests, such as version checkboxes, required sections, HTML comments, related-link fields, and cherry-pick conventions
- `.ai/skills/docs-issue-metadata-guard/`: guard issue template structure when creating or editing issues, such as template selection, required fields, scope boundaries, and label hygiene

Expand Down
97 changes: 40 additions & 57 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
@@ -1,34 +1,36 @@
---
name: release-notes
description: Write, review, revise, 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/`.
description: Write, review, revise, and translate TiDB release notes for the Feature details/Features, 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

When you write, review, or translate a release note entry, use this skill to load the right references, apply the correct patterns, and produce output that matches the published format in `releases/` (`pingcap/docs` for English, `pingcap/docs-cn` for Chinese) for v6.1.0 and later.
When you write, review, or translate a release note entry (including feature descriptions, compatibility changes, improvements, and bug fixes), use this skill to load the right references, apply the correct patterns, and produce output that matches the published format in `releases/` (`pingcap/docs` for English, `pingcap/docs-cn` for 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
- **Writing a new feature description** for the Feature details or Features section based on a GitHub PR, issue description, or product brief
- **Writing a new entry** for the Compatibility changes, Improvements, or Bug fixes section based on a GitHub PR or issue description
- **Reviewing or revising** an existing English or Chinese release note entry or section, such as correcting the structure, 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.
This skill applies to the recurring sections in every `release-X.X.X.md` file: Feature details / Features, Compatibility changes, Improvements, and Bug fixes.

## Which reference to load

Load only what is necessary for the task:

| Task | Load |
|------|------|
| Feature descriptions (title line, before-after structure, GA/experimental tags, examples) | [references/feature-description.md](references/feature-description.md) |
| Compatibility changes (upgrade note block, behavior-change paragraph, system-variable table, config-parameter table, anchor suffixes) | [references/compatibility-changes.md](references/compatibility-changes.md) |
| Improvement entries (opening verbs, English and Chinese patterns, examples) | [references/improvements.md](references/improvements.md) |
| Bug-fix entries (fix templates, anti-patterns, English and Chinese patterns, examples) | [references/bug-fixes.md](references/bug-fixes.md) |
| Translation, bilingual alignment check, or auditing paired files | [references/bilingual-alignment.md](references/bilingual-alignment.md) |

A Chinese-only bug-fix revision does not need the compatibility-changes file. For a full bilingual audit, load all four.
A Chinese-only bug-fix revision does not need the compatibility-changes file. For a full bilingual audit, load all five.

## File-level structure

Expand All @@ -37,7 +39,7 @@
```markdown
---
title: TiDB X.X.X Release Notes
summary: Learn about the compatibility changes, improvements, and bug fixes in TiDB X.X.X.
summary: Learn about the features, compatibility changes, improvements, and bug fixes in TiDB X.X.X.
---

# TiDB X.X.X Release Notes
Expand All @@ -49,14 +51,17 @@
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.
The `summary` value lists the sections actually present in the file, in the same order as the level-2 headings. If a section is absent, omit it from the summary. Examples:

- With all sections: `Learn about the new features, compatibility changes, improvements, and bug fixes in TiDB X.X.X.`
- Without features: `Learn about the compatibility changes, improvements, and bug fixes in TiDB X.X.X.`

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

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

# TiDB X.X.X Release Notes
Expand All @@ -72,6 +77,18 @@

| English | Chinese |
|---------|---------|
| `## Feature details` | `## 功能详情` |
| `## Features` | `## 功能` |
| `### Scalability` | `### 可扩展性` |
| `### Performance` | `### 性能` |
| `### Reliability` | `### 稳定性` |
| `### Availability` | `### 可用性` |
| `### SQL` | `### SQL` |
| `### DB Operations and Observability` | `### 数据库管理与可观测性` |
| `### DB operations` | `### 数据库管理` |
| `### Observability` | `### 可观测性` |
| `### Security` | `### 安全` |
| `### Data Migration` | `### 数据迁移` |
| `## Compatibility changes` | `## 兼容性变更` |
| `### Behavior changes` | `### 行为变更` |
| `### System variables` | `### 系统变量` |
Expand All @@ -82,21 +99,18 @@
| `## 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
## Cross-cutting rules

Entries do not end with `.` (English) or `。` (Chinese).
These rules apply to all sections (Features, Compatibility changes, Improvements, and Bug fixes) in both languages. Each reference file assumes these conventions.

### Write from the user's perspective

Describe what the user observes, not what the code does.
Describe what the user observes, gains, or can do — not what the code does internally.

Check failure on line 108 in .ai/skills/write-review-translate-release-notes/SKILL.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/SKILL.md", "range": {"start": {"line": 108, "column": 50}}}, "severity": "ERROR"}

- Bug fixes: start from the GitHub issue description (user-facing symptoms). Avoid exposing internal function or variable names.
- Feature descriptions: explain the capability, the problem it solves, and the user benefit.
- 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.
- Bug fixes: start from the GitHub issue description (user-facing symptoms). Avoid exposing internal function or variable names.
- 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. A complete feature description covers the before state, the after state, and the user value.

### Inline code

Expand All @@ -112,53 +126,22 @@

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
### Issue and contributor links

Each improvement and bug-fix entry ends with issue link(s) and contributor, in the following format:
Every entry (feature, improvement, or bug fix) ends with issue link(s) and contributor link(s) on the title line:

Check failure on line 131 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": 131, "column": 88}}}, "severity": "ERROR"}

Check failure on line 131 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": 131, "column": 64}}}, "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] 的问题
```
For multiple issues: `[#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) [#MMMMM](https://github.com/pingcap/tidb/issues/MMMMM) @[contributor](https://github.com/contributor)`

### Improvement opening verbs
### No trailing period on single-line entries

English: `Support`, `Add`, `Optimize`, `Improve`, `Avoid`, `Enhance`, `Mitigate`, `Accelerate`, `Remove`, `Increase`
Improvement and bug-fix entries (single-line entries starting with `-`) do not end with `.` (English) or `。` (Chinese).

Chinese: `支持`、`新增`、`优化`、`提升`、`避免`、`改进`、`引入`、`增加`
Feature entries follow a different convention: the title line (starting with `*`) omits the trailing period, but body paragraphs use normal sentence punctuation. See [references/feature-description.md](references/feature-description.md) for details.

For verb selection guidance and examples, see [references/improvements.md](references/improvements.md).

### Compatibility change-type vocabulary

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

Component names in section headers are identical in English and Chinese: `TiDB`, `TiKV`, `PD`, `TiFlash`, `TiDB Lightning`, `BR`, `TiCDC`.
Component names are identical in English and Chinese across all sections: `TiDB`, `TiKV`, `PD`, `TiFlash`, `TiDB Lightning`, `BR`, `TiCDC`.
19 changes: 12 additions & 7 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
Expand Up @@ -55,18 +55,19 @@

### Reviewing an existing entry

1. Identify the section (Compatibility changes, Improvements, or Bug fixes) and load the corresponding reference file
1. Identify the section (Feature details/Features, Compatibility changes, Improvements, or Bug fixes) and load the corresponding reference file
2. Check the opening pattern against section rules
3. Verify trailing punctuation (no `.` in English; no `。` in Chinese)
3. Verify trailing punctuation: single-line entries (improvements, bug fixes) must not end with `.` / `。`; feature body paragraphs use normal sentence punctuation
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
5. Verify the issue link and contributor link at the end of the title line
6. For Chinese entries: verify `修复` as the opening verb for bug fixes, an approved opening verb for improvements, or the correct verb mapping for feature title lines (see [feature-description.md](feature-description.md))

### 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:
- Feature description: `* [Feature title] (maturity tag) [#NNNNN](...) @[contributor](...)` followed by before-after body paragraphs — for structure and examples, see [feature-description.md](feature-description.md)

Check failure on line 70 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": 70, "column": 136}}}, "severity": "ERROR"}
- 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)` — for approved opening verbs and usage guidance, see [improvements.md](improvements.md)
4. Draft the Chinese entry with the matching pattern
Expand All @@ -75,25 +76,29 @@

## English to Chinese translation

1. Identify if the entry is a bug fix or improvement
1. Identify if the entry is a feature description, bug fix, or improvement
2. Map the opening verb/phrase:
- Feature title: `Support X` → `支持 [X]`; `Introduce X` → `引入 [X]`; `Add X` → `新增 [X]` — for full mapping, see [feature-description.md](feature-description.md)

Check failure on line 81 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": 81, "column": 89}}}, "severity": "ERROR"}
- Feature body: `Before vX.Y.Z, ...` → `在 vX.Y.Z 之前，……`; `Starting from vX.Y.Z, ...` → `从 vX.Y.Z 开始，……`
- `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
6. For single-line entries (improvements, bug fixes): do not add a trailing period. For feature body paragraphs: use normal sentence punctuation

## Chinese to English translation

1. Identify the pattern:
- Feature title: `支持 [X]` → `Support [X]`; `引入 [X]` → `Introduce [X]`; `新增 [X]` → `Add [X]` — for full mapping, see [feature-description.md](feature-description.md)

Check failure on line 95 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": 95, "column": 95}}}, "severity": "ERROR"}
- Feature body: `在 vX.Y.Z 之前，……` → `Before vX.Y.Z, ...`; `从 vX.Y.Z 开始，……` → `Starting from vX.Y.Z, ...`
- `修复 [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
5. For single-line entries (improvements, bug fixes): do not add a trailing period. For feature body paragraphs: use normal sentence punctuation
2 changes: 1 addition & 1 deletion .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
@@ -1,6 +1,6 @@
# 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.
Rules for the `## Bug fixes` / `## 错误修复` section. The cross-cutting rules in SKILL.md (user perspective, inline-code conventions, issue and contributor links, and no trailing period on single-line entries) 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.

Expand Down
Loading
Loading