From 946b08f472622ac48e83e59dd756fb478a011aff Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 11 Jun 2026 14:26:44 +0800 Subject: [PATCH 1/2] add skills for writing feature descriptions --- .ai/AI-README.md | 2 +- .../SKILL.md | 97 ++--- .../references/bilingual-alignment.md | 19 +- .../references/bug-fixes.md | 2 +- .../references/feature-description.md | 378 ++++++++++++++++++ .../references/improvements.md | 2 +- 6 files changed, 433 insertions(+), 67 deletions(-) create mode 100644 .ai/skills/write-review-translate-release-notes/references/feature-description.md diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 45802a018e4f3..33ef013044bcd 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -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 The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for: diff --git a/.ai/skills/write-review-translate-release-notes/SKILL.md b/.ai/skills/write-review-translate-release-notes/SKILL.md index 3ff4c1ae04a6e..f3cdfc255fec6 100644 --- a/.ai/skills/write-review-translate-release-notes/SKILL.md +++ b/.ai/skills/write-review-translate-release-notes/SKILL.md @@ -1,21 +1,22 @@ --- 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 @@ -23,12 +24,13 @@ 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 @@ -37,7 +39,7 @@ A Chinese-only bug-fix revision does not need the compatibility-changes file. Fo ```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 @@ -49,14 +51,17 @@ 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. +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 @@ -72,6 +77,18 @@ TiDB 版本：X.X.X | 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` | `### 系统变量` | @@ -82,21 +99,18 @@ TiDB 版本：X.X.X | `## 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. -- 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 @@ -112,53 +126,22 @@ Use backticks for: 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: ``` [#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`. diff --git a/.ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md b/.ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md index b8a877ecdf155..2ebacde8d86ab 100644 --- a/.ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md +++ b/.ai/skills/write-review-translate-release-notes/references/bilingual-alignment.md @@ -55,18 +55,19 @@ Use this file for checking English/Chinese alignment of a paired release note fi ### 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) - 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 @@ -75,8 +76,10 @@ Use this file for checking English/Chinese alignment of a paired release note fi ## 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) + - 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] 的问题` @@ -84,11 +87,13 @@ Use this file for checking English/Chinese alignment of a paired release note fi 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) + - 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]` @@ -96,4 +101,4 @@ Use this file for checking English/Chinese alignment of a paired release note fi 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 diff --git a/.ai/skills/write-review-translate-release-notes/references/bug-fixes.md b/.ai/skills/write-review-translate-release-notes/references/bug-fixes.md index 743d4a2b70cbc..ae28aa35812f5 100644 --- a/.ai/skills/write-review-translate-release-notes/references/bug-fixes.md +++ b/.ai/skills/write-review-translate-release-notes/references/bug-fixes.md @@ -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. diff --git a/.ai/skills/write-review-translate-release-notes/references/feature-description.md b/.ai/skills/write-review-translate-release-notes/references/feature-description.md new file mode 100644 index 0000000000000..605189514875e --- /dev/null +++ b/.ai/skills/write-review-translate-release-notes/references/feature-description.md @@ -0,0 +1,378 @@ +# Feature descriptions + +Rules for the `## Feature details` (major/DMR releases) and `## Features` (patch releases) sections. The cross-cutting rules in SKILL.md (user perspective, inline-code conventions, issue and contributor links, and component names) also apply here. + +## Contents + +- Section heading and grouping +- Entry structure (anatomy of a feature description) +- Title line conventions +- Body paragraphs: structure and required content +- Documentation link +- GA, experimental, and version-lifecycle language +- Style rules (tone, sentence structure, metrics, trailing periods, Chinese-specific) +- Differences between major and patch releases +- Common review findings + +## Section heading and grouping + +### Major and DMR releases + +Major releases (for example, v8.5.0) and DMR releases (for example, v8.4.0-DMR) use `## Feature details` as the section heading. + +Features are grouped under level-3 category headings. Common categories include: + +- `### Scalability` +- `### Performance` +- `### Reliability` +- `### Availability` +- `### SQL` +- `### DB Operations and Observability` (or separate `### DB operations` and `### Observability`) +- `### Security` +- `### Data Migration` + +Each feature is a top-level bullet (`*`) followed by one or more indented body paragraphs. + +### Patch releases + +Patch releases (for example, v8.5.4, v8.5.5) use `## Features` as the section heading. + +When there are enough features, they are grouped under the same level-3 category headings as major releases. When a patch has only a few features and no clear grouping, features may appear as direct children of `## Features` without level-3 headings (as in v8.5.4). + +For the full EN/ZH heading mapping, see the section heading mapping table in [SKILL.md](../SKILL.md). + +## Entry structure + +A complete feature description contains up to five parts, in order: + +### 1. Title line + +The title line is the first line of the entry. It serves as a concise summary of the feature. It includes the feature name, maturity tag, issue/PR links, and contributor links. + +### 2. Before paragraph (the problem or limitation) + +Describes the situation before this feature exists, or the problem/limitation this feature addresses. This sets the context and motivation. + +### 3. After paragraph (what changes starting from this version) + +Describes what the feature does and how it works starting from this version. This is the core of the description. + +### 4. Additional details (optional) + +Provides supplementary information such as caveats, limitations, usage notes, configuration details, or performance benchmarks. May use sub-lists, tables, or code examples. + +### 5. Documentation link + +A closing line that points the reader to detailed documentation. + +Not all five parts are always present. The minimum viable entry includes the title line, the after paragraph, and the documentation link. The before paragraph is strongly recommended for any feature that changes existing behavior or solves a pre-existing limitation. + +## Title line conventions + +### Format + +The title line starts with `*` (not `-`), followed by the feature name and a maturity tag (if applicable), then issue/PR links and contributor links. + +``` +* Feature name (maturity tag) [#NNNNN](https://github.com/org/repo/issues/NNNNN) @[contributor](https://github.com/contributor) +``` + +### Maturity tags + +| Tag | When to use | English | Chinese | +|-----|-------------|---------|---------| +| GA | Feature reaches general availability in this version | `(GA)` or `(GA in vX.Y.Z)` | `(GA)` | +| Experimental | Feature is newly introduced as experimental | `(experimental)` | `(实验特性)` | +| GA from experimental | Feature transitions from experimental to GA | Include version history in the title or body | Same | + +Examples: + +- `* Support foreign keys (GA) [#36982](...)` +- `* Support redistributing data of a specific table (experimental) [#63260](...)` +- `* TiDB accelerated table creation becomes generally available (GA), significantly reducing data migration and cluster initialization time [#50052](...)` + +### Title style + +The title is a concise noun phrase or verb phrase that names the feature and its key benefit. Two common patterns: + +**Pattern A: Verb phrase describing the capability** + +``` +* Support foreign keys (GA) [#36982](...) @[YangKeao](...) +* Support pushing index lookups down to TiKV to improve query performance [#62575](...) @[lcwangchao](...) +* Support gracefully shutting down TiFlash [#10266](...) @[gengliqi](...) +``` + +**Pattern B: Noun phrase naming the feature with a benefit clause** + +``` +* TiDB accelerated table creation becomes generally available (GA), significantly reducing data migration and cluster initialization time [#50052](...) @[D3Hunter](...) +* Introduce significant performance improvements for certain lossy DDL operations ... [#63366](...) @[wjhuang2016](...) +* Foreign key checks now support shared locks [#66154](...) @[you06](...) +``` + +**Pattern C: Descriptive phrase for GA transitions (version-history style)** + +``` +* Setting the memory limit for schema cache is now generally available (GA). When the number of tables reaches hundreds of thousands or even millions, this feature significantly reduces the memory usage of schema metadata [#50959](...) @[tiancaiamao](...) +* Provide the Active PD Follower feature to enhance the scalability of PD's Region information query service (GA) [#7431](...) @[okJiang](...) +``` + +### Verbs used in title lines + +| Verb | Usage | +|------|-------| +| `Support` | New capability: `Support column-level privilege management`, `Support gracefully shutting down TiFlash` | +| `Introduce` | New mechanism or architecture: `Introduce a new TiCDC architecture option for improved performance, scalability, and stability` | +| `Provide` | Provide a feature or service: `Provide the Active PD Follower feature to enhance the scalability of PD's Region information query service` | +| `Add` | New element (field, parameter, identifier): `Add storage engine identifiers to statement summary tables and slow query logs` | +| `Improve` | Enhancement: `Improve DDL performance in scenarios with a large number of foreign keys` | +| `Accelerate` | Speed improvement: `Accelerate recovery of system tables from backups` | + +### No trailing period on title lines + +Title lines do not end with `.` (English) or `。` (Chinese). + +## Body paragraphs + +### Before paragraph + +Describes the world before this feature. Common patterns: + +**English** + +- `Before vX.Y.Z, ...` +- `In earlier versions, ...` +- `In TiDB versions earlier than vX.Y.Z, ...` +- Problem-oriented: directly states the limitation without a version prefix + +**Chinese** + +- `在 vX.Y.Z 之前，……` +- `在此前版本中，……` +- `在 vX.Y.Z 之前的版本中，……` + +The before paragraph establishes the motivation: why the user should care about this feature. It typically describes a limitation, a pain point, or a suboptimal behavior. + +### After paragraph + +Describes the new behavior starting from this version. Common patterns: + +**English** + +- `Starting from vX.Y.Z, ...` +- `In vX.Y.Z, ...` +- `TiDB vX.Y.Z introduces ...` +- `TiDB vX.Y.Z optimizes ...` + +**Chinese** + +- `从 vX.Y.Z 开始，……` +- `在 vX.Y.Z 中，……` +- `TiDB vX.Y.Z 引入……` +- `TiDB vX.Y.Z 优化了……` + +The after paragraph answers: what the feature does, how it works (briefly), and what the user gains. + +### Before-after structure examples + +**Example 1: Problem → solution (v8.5.6, column-level privilege)** + +```markdown +* Support column-level privilege management [#61706](...) @[CbcWestwolf](...) @[fzzf678](...) + + Before v8.5.6, TiDB privilege control covers the database and table levels and does not support granting or revoking privileges on specific columns, unlike MySQL. As a result, you cannot restrict users to access only a subset of sensitive columns in a table. + + Starting from v8.5.6, TiDB supports column-level privilege management. You can use the `GRANT` and `REVOKE` statements to manage privileges on specific columns. TiDB performs privilege checks based on column-level privileges during query processing and execution plan construction, enabling finer-grained access control and better support for sensitive data isolation and the principle of least privilege. + + For more information, see [documentation](...). +``` + +**Example 2: GA transition with version history (v8.5.0, schema cache)** + +```markdown +* Setting the memory limit for schema cache is now generally available (GA). When the number of tables reaches hundreds of thousands or even millions, this feature significantly reduces the memory usage of schema metadata [#50959](...) @[tiancaiamao](...) + + In some SaaS scenarios, where the number of tables reaches hundreds of thousands or even millions, schema metadata can consume a significant amount of memory. With this feature enabled, TiDB uses the Least Recently Used (LRU) algorithm to cache and evict the corresponding schema metadata, effectively reducing memory usage. + + Starting from v8.4.0, this feature is enabled by default with a default value of `536870912` (that is, 512 MiB). You can adjust it as needed using the variable [`tidb_schema_cache_size`](/system-variables.md#tidb_schema_cache_size-new-in-v800). + + For more information, see [documentation](/schema-cache.md). +``` + +**Example 3: New feature with performance benchmarks (v8.5.5, lossy DDL)** + +```markdown +* Introduce significant performance improvements for certain lossy DDL operations (...) [#63366](...) @[wjhuang2016](...) + + The optimization strategies are as follows: + + - In strict SQL mode, TiDB pre-checks for potential data truncation risks during type conversion. + - If no data truncation risk is detected, TiDB updates only the metadata and avoids index rebuilding whenever possible. + - If index rebuilding is required, TiDB uses a more efficient ingest process to significantly improve index rebuild performance. + + The following table shows example performance improvements based on benchmark tests ... + + | Scenario | Operation type | Before optimization | After optimization | Performance improvement | + |----------|----------------|---------------------|--------------------|--------------------------| + | Non-indexed column | `BIGINT → INT` | 2 hours 34 minutes | 1 minute 5 seconds | 142× faster | + | Indexed column | `BIGINT → INT` | 6 hours 25 minutes | 0.05 seconds | 460,000× faster | + | Indexed column | `CHAR(120) → VARCHAR(60)` | 7 hours 16 minutes | 12 minutes 56 seconds | 34× faster | + + Note that the preceding test results are based on the condition that no data truncation occurs ... + + For more information, see [documentation](...). +``` + +**Example 4: New architecture with caveats (v8.5.4, TiCDC architecture)** + +```markdown +* Introduce a new TiCDC architecture option for improved performance, scalability, and stability [#442](...) @[CharlesCheung96](...) + + This new architecture redesigns TiCDC core components and optimizes its data processing workflows, while maintaining compatibility with the configuration, usage, and APIs of the classic TiCDC architecture. + + When configured to use this new architecture, TiCDC achieves near-linear scalability and can replicate millions of tables with lower resource consumption. It also reduces changefeed latency and delivers more stable performance in scenarios with high write workloads, frequent DDL operations, and cluster scaling. Note that the new architecture currently has some initial limitations. + + To use the new architecture, set the TiCDC configuration item [`newarch`](...) to `true`. + + For more information, see [documentation](...). +``` + +### Additional details + +When extra context is needed, use one or more of the following patterns after the before-after paragraphs: + +- **Configuration or usage instructions**: describe how to enable, configure, or use the feature. Include variable names, configuration items, SQL statements, or command-line flags in backticks. +- **Performance benchmarks**: include a table or inline metrics when available. State the test conditions (cluster spec, data size). +- **Caveats and limitations**: describe restrictions, unsupported scenarios, or known issues. Use phrasing like `Note that ...` or a separate paragraph. +- **Sub-list of capabilities**: use `-` items indented under the main entry for enumerating sub-features, supported operations, or optimization strategies. +- **Behavior details**: describe behavior for different conditions (for example, "If X finishes before timeout, Y. If X does not finish, Z."). + +## Documentation link + +Every feature entry ends with a documentation link. + +**English** + +```markdown + For more information, see [documentation](/path-to-doc.md). + For more information, see [documentation](/path-to-doc.md#anchor). +``` + +**Chinese** + +```markdown + 更多信息，请参考[用户文档](/path-to-doc.md)。 + 更多信息，请参考[用户文档](/path-to-doc.md#锚点)。 +``` + +The documentation link is indented at the same level as the body paragraphs (4 spaces under the `*` title line). Both English and Chinese doc link lines end with a period (`.` for English, `。` for Chinese), because they are full sentences within body paragraphs. + +## GA, experimental, and version-lifecycle language + +### GA features + +When a feature transitions to GA, the description should briefly mention its history: + +- `The foreign key feature becomes generally available (GA) in v8.5.0.` +- `Starting from v8.5.0, this feature becomes generally available (GA).` +- `In v8.2.0, this feature becomes generally available (GA) and is enabled by default.` +- `TiDB v7.6.0 introduces X as an experimental feature. ... In v8.5.0, this feature becomes generally available (GA).` + +Chinese equivalents: + +- `外键功能在 v8.5.0 中正式 GA。` +- `从 v8.5.0 开始，该功能正式 GA。` + +### Experimental features + +When a feature is introduced as experimental, state this clearly: + +- `(experimental)` in the title tag +- `This feature is currently experimental and is disabled by default.` in the body (if applicable) + +### Version-history references + +For features first introduced in an earlier version, mention the version history: + +- `TiDB v7.6.0 introduces X as an experimental feature, controlled by the system variable [`Y`](...). Starting from v8.0.0, this system variable is renamed to [`Z`](...).` +- `In v8.0.0, TiKV encryption at rest experimentally supports using Google Cloud KMS. Starting from v8.5.0, this feature becomes generally available (GA).` + +## Style rules + +### Tone and perspective + +- Write from the user's perspective. Describe what the user can do, what the user observes, or what changes for the user. +- Use present tense for describing the feature's behavior: "TiDB supports ...", "You can use ...". +- Use imperative mood for configuration instructions: "Set the variable to ...", "To enable this feature, ...". + +### Sentence structure + +- Lead with the most important information. State the capability or benefit before describing the mechanism. +- Avoid passive voice when active voice is natural: prefer "TiDB supports X" over "X is supported by TiDB". +- Use concise compound sentences. Avoid overly long sentences; break complex descriptions into separate sentences. + +### Metric claims + +Performance claims should include: + +- The metric type (for example, "performance", "QPS", "latency") +- The magnitude (for example, "up to 25x", "by 62.5%", "from hours to seconds") +- The test conditions when available (cluster spec, data size) + +### Trailing period convention + +Feature body paragraphs use normal sentence punctuation with trailing periods. Only the title line omits the trailing period. This differs from single-line improvement and bug-fix entries, which omit the trailing period entirely. + +### Chinese-specific rules + +Chinese title lines follow the same verb patterns as English but use Chinese verbs: + +| English verb | Chinese equivalent | +|-------------|-------------------| +| `Support` | `支持` | +| `Introduce` | `引入` | +| `Provide` | `提供` | +| `Add` | `新增` | +| `Improve` | `提升` / `优化` | +| `Accelerate` | `加速` | + +Before-after phrasing: + +- Before: `在 vX.Y.Z 之前，……` / `在此前版本中，……` +- After: `从 vX.Y.Z 开始，……` / `TiDB vX.Y.Z 引入了……` + +Punctuation: + +- Use full-width punctuation in Chinese prose: `，`、`。`、`（`、`）`、`：` +- Documentation link sentence ends with `。`: `更多信息，请参考[用户文档](/path.md)。` +- Title lines do not end with `。` + +## Differences between major and patch releases + +| Aspect | Major/DMR release | Patch release | +|--------|-------------------|---------------| +| Section heading | `## Feature details` | `## Features` | +| Level-3 category headings | Always present | Present when there are enough features; may be omitted for a small number of features | +| Highlight table | Major releases may include an HTML `` summary of highlights at the top of the file, before `## Feature details` | Not present | +| Scope | New features, GA transitions, and major capability additions | Backported features, GA transitions, and incremental capability additions | +| Version-history detail | More detailed for features that evolved over multiple DMR cycles | Typically shorter; references the original introduction version | + +## Common review findings + +| Finding | Correct | +|---------|---------| +| Entry uses `-` instead of `*` for the title line | Use `*` for the feature title line (sub-items within the body use `-`) | +| Missing before paragraph for a feature that addresses a pre-existing limitation | Add a before paragraph describing the limitation or pain point | +| Missing documentation link | Add `For more information, see [documentation](/path.md).` | +| Title line ends with `.` | Remove the trailing period from the title line | +| Body omits the version number in `Starting from ...` | Always specify the version: `Starting from v8.5.5, ...` | +| GA transition does not mention the original experimental version | Add version history: `Introduced as experimental in vX.Y.Z.` | +| Feature description only explains what the code does, not the user benefit | Rewrite to explain what the user gains (capability, performance, stability) | +| Chinese doc link missing `。` | Chinese doc link line ends with `。`: `更多信息，请参考[用户文档](/path.md)。` | +| English doc link missing `.` | English doc link line ends with `.`: `For more information, see [documentation](/path.md).` | +| Performance claim without test conditions | Add test environment details (cluster spec, data size) when available | +| Maturity tag missing for experimental features | Add `(experimental)` to the title | +| Maturity tag missing for GA transitions | Add `(GA)` or `(GA in vX.Y.Z)` to the title | +| Chinese anchor uses English suffix | Change `-new-in-vXYZ` to `-从-vXYZ-版本开始引入` in Chinese entries | +| Inline code not applied to variables, configs, or SQL keywords | Apply backtick formatting per the inline-code rules in SKILL.md | diff --git a/.ai/skills/write-review-translate-release-notes/references/improvements.md b/.ai/skills/write-review-translate-release-notes/references/improvements.md index 307c4f8edac08..9ccd047a87d50 100644 --- a/.ai/skills/write-review-translate-release-notes/references/improvements.md +++ b/.ai/skills/write-review-translate-release-notes/references/improvements.md @@ -1,6 +1,6 @@ # Improvements -Rules for the `## Improvements` / `## 改进提升` 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 `## Improvements` / `## 改进提升` 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. ## Contents From 28412f25cc487c7c958ff9efadab2e14c416f0af Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 11 Jun 2026 17:00:38 +0800 Subject: [PATCH 2/2] Update feature-description.md --- .../references/feature-description.md | 408 +++++++----------- 1 file changed, 144 insertions(+), 264 deletions(-) diff --git a/.ai/skills/write-review-translate-release-notes/references/feature-description.md b/.ai/skills/write-review-translate-release-notes/references/feature-description.md index 605189514875e..1f8d640a121ad 100644 --- a/.ai/skills/write-review-translate-release-notes/references/feature-description.md +++ b/.ai/skills/write-review-translate-release-notes/references/feature-description.md @@ -1,378 +1,258 @@ # Feature descriptions -Rules for the `## Feature details` (major/DMR releases) and `## Features` (patch releases) sections. The cross-cutting rules in SKILL.md (user perspective, inline-code conventions, issue and contributor links, and component names) also apply here. +Use this reference to write one TiDB release note feature description from PM or engineering input, such as a short feature brief, GitHub issue links, PR links, feature specification, benchmark results, and documentation links. -## Contents +The goal is not to summarize implementation work. The goal is to produce a user-facing entry that matches the `## Feature details` or `## Features` style in current TiDB release notes: clear title, concrete user problem, new capability in this version, user value, and a documentation link. -- Section heading and grouping -- Entry structure (anatomy of a feature description) -- Title line conventions -- Body paragraphs: structure and required content -- Documentation link -- GA, experimental, and version-lifecycle language -- Style rules (tone, sentence structure, metrics, trailing periods, Chinese-specific) -- Differences between major and patch releases -- Common review findings +The cross-cutting rules in [SKILL.md](../SKILL.md) also apply, especially user perspective, inline-code formatting, issue and contributor links, and component names. + +## Quick workflow -## Section heading and grouping +1. Read the supplied issue, PR, feature brief, and related documentation. +2. Extract only user-facing facts: + - What problem, limitation, or scenario does this feature address? + - What can users do starting from this version? + - How do users enable, configure, or use it? + - What benefit does it bring, such as performance, scalability, stability, compatibility, security, operability, or observability? + - What maturity state applies: GA, experimental, or no maturity tag? + - What caveats, unsupported cases, or benchmark conditions must be stated? +3. Decide whether the change belongs in a feature entry. If it is a small behavior improvement, bug fix, or internal refactor with no new user-facing capability, use the Improvements or Bug fixes reference instead. +4. Draft the entry using the standard structure: title line, context paragraph, new behavior paragraph, optional details, and documentation link. +5. Check every technical claim against the source input. Do not invent defaults, limits, metrics, maturity state, or documentation links. -### Major and DMR releases +## Section placement in the release note file -Major releases (for example, v8.5.0) and DMR releases (for example, v8.4.0-DMR) use `## Feature details` as the section heading. +```markdown +## Features +``` -Features are grouped under level-3 category headings. Common categories include: +Use level-3 category headings when the release groups features by area. Common categories are: - `### Scalability` - `### Performance` - `### Reliability` - `### Availability` - `### SQL` -- `### DB Operations and Observability` (or separate `### DB operations` and `### Observability`) +- `### DB Operations and Observability` +- `### DB operations` +- `### Observability` - `### Security` - `### Data Migration` -Each feature is a top-level bullet (`*`) followed by one or more indented body paragraphs. - -### Patch releases - -Patch releases (for example, v8.5.4, v8.5.5) use `## Features` as the section heading. - -When there are enough features, they are grouped under the same level-3 category headings as major releases. When a patch has only a few features and no clear grouping, features may appear as direct children of `## Features` without level-3 headings (as in v8.5.4). - -For the full EN/ZH heading mapping, see the section heading mapping table in [SKILL.md](../SKILL.md). - -## Entry structure - -A complete feature description contains up to five parts, in order: - -### 1. Title line +For Chinese heading mappings, see [SKILL.md](../SKILL.md). -The title line is the first line of the entry. It serves as a concise summary of the feature. It includes the feature name, maturity tag, issue/PR links, and contributor links. +When writing the description for a feature, consider which category the feature belongs to and use the appropriate heading. -### 2. Before paragraph (the problem or limitation) +## Entry shape -Describes the situation before this feature exists, or the problem/limitation this feature addresses. This sets the context and motivation. +Prefer this shape for a complete feature description: -### 3. After paragraph (what changes starting from this version) - -Describes what the feature does and how it works starting from this version. This is the core of the description. - -### 4. Additional details (optional) - -Provides supplementary information such as caveats, limitations, usage notes, configuration details, or performance benchmarks. May use sub-lists, tables, or code examples. - -### 5. Documentation link - -A closing line that points the reader to detailed documentation. - -Not all five parts are always present. The minimum viable entry includes the title line, the after paragraph, and the documentation link. The before paragraph is strongly recommended for any feature that changes existing behavior or solves a pre-existing limitation. +```markdown +* [#NNNNN](https://github.com/org/repo/issues/NNNNN) @[contributor](https://github.com/contributor) -## Title line conventions + Before vX.Y.Z, . -### Format + Starting from vX.Y.Z, . -The title line starts with `*` (not `-`), followed by the feature name and a maturity tag (if applicable), then issue/PR links and contributor links. + + For more information, see [documentation](/path-to-doc.md). ``` -* Feature name (maturity tag) [#NNNNN](https://github.com/org/repo/issues/NNNNN) @[contributor](https://github.com/contributor) -``` - -### Maturity tags - -| Tag | When to use | English | Chinese | -|-----|-------------|---------|---------| -| GA | Feature reaches general availability in this version | `(GA)` or `(GA in vX.Y.Z)` | `(GA)` | -| Experimental | Feature is newly introduced as experimental | `(experimental)` | `(实验特性)` | -| GA from experimental | Feature transitions from experimental to GA | Include version history in the title or body | Same | -Examples: +Minimum viable entry: -- `* Support foreign keys (GA) [#36982](...)` -- `* Support redistributing data of a specific table (experimental) [#63260](...)` -- `* TiDB accelerated table creation becomes generally available (GA), significantly reducing data migration and cluster initialization time [#50052](...)` - -### Title style +- Title line +- One paragraph that states the new behavior and user value +- Documentation link -The title is a concise noun phrase or verb phrase that names the feature and its key benefit. Two common patterns: +Add a before paragraph when the feature solves a known limitation, changes an existing workflow, or needs motivation to be understandable. -**Pattern A: Verb phrase describing the capability** +## Title line -``` -* Support foreign keys (GA) [#36982](...) @[YangKeao](...) -* Support pushing index lookups down to TiKV to improve query performance [#62575](...) @[lcwangchao](...) -* Support gracefully shutting down TiFlash [#10266](...) @[gengliqi](...) -``` +The title line should name the capability and, when useful, include the main benefit. It is usually a verb phrase. -**Pattern B: Noun phrase naming the feature with a benefit clause** +Common title patterns: +```markdown +* Support [#NNNNN](...) @[contributor](...) +* Support to improve [#NNNNN](...) @[contributor](...) +* Introduce for [#NNNNN](...) @[contributor](...) +* Add [#NNNNN](...) @[contributor](...) +* Improve , with [#NNNNN](...) @[contributor](...) +* becomes generally available (GA) [#NNNNN](...) @[contributor](...) ``` -* TiDB accelerated table creation becomes generally available (GA), significantly reducing data migration and cluster initialization time [#50052](...) @[D3Hunter](...) -* Introduce significant performance improvements for certain lossy DDL operations ... [#63366](...) @[wjhuang2016](...) -* Foreign key checks now support shared locks [#66154](...) @[you06](...) -``` - -**Pattern C: Descriptive phrase for GA transitions (version-history style)** - -``` -* Setting the memory limit for schema cache is now generally available (GA). When the number of tables reaches hundreds of thousands or even millions, this feature significantly reduces the memory usage of schema metadata [#50959](...) @[tiancaiamao](...) -* Provide the Active PD Follower feature to enhance the scalability of PD's Region information query service (GA) [#7431](...) @[okJiang](...) -``` - -### Verbs used in title lines -| Verb | Usage | -|------|-------| -| `Support` | New capability: `Support column-level privilege management`, `Support gracefully shutting down TiFlash` | -| `Introduce` | New mechanism or architecture: `Introduce a new TiCDC architecture option for improved performance, scalability, and stability` | -| `Provide` | Provide a feature or service: `Provide the Active PD Follower feature to enhance the scalability of PD's Region information query service` | -| `Add` | New element (field, parameter, identifier): `Add storage engine identifiers to statement summary tables and slow query logs` | -| `Improve` | Enhancement: `Improve DDL performance in scenarios with a large number of foreign keys` | -| `Accelerate` | Speed improvement: `Accelerate recovery of system tables from backups` | +Title rules: -### No trailing period on title lines - -Title lines do not end with `.` (English) or `。` (Chinese). +- Use the same bullet marker as the surrounding release file. Existing feature entries commonly use `*`; some patch release files use `-`. +- Do not end the title line with `.` or `。`. +- Include all relevant issue links and contributor links. +- Use `(experimental)` for experimental features. +- Use `(GA)` when a feature becomes generally available. +- Keep the title concise. Move explanation, conditions, and caveats into the body. ## Body paragraphs -### Before paragraph +### Context paragraph -Describes the world before this feature. Common patterns: +Use the context paragraph to explain why the feature matters. It usually describes the previous limitation or user scenario. -**English** +Common English openings: - `Before vX.Y.Z, ...` -- `In earlier versions, ...` - `In TiDB versions earlier than vX.Y.Z, ...` -- Problem-oriented: directly states the limitation without a version prefix +- `In earlier versions, ...` +- `.` -**Chinese** +Common Chinese openings: - `在 vX.Y.Z 之前，……` -- `在此前版本中，……` - `在 vX.Y.Z 之前的版本中，……` +- `在此前版本中，……` -The before paragraph establishes the motivation: why the user should care about this feature. It typically describes a limitation, a pain point, or a suboptimal behavior. - -### After paragraph +### New behavior paragraph -Describes the new behavior starting from this version. Common patterns: +Use the new behavior paragraph to explain what changes in this version and what users gain. -**English** +Common English openings: - `Starting from vX.Y.Z, ...` - `In vX.Y.Z, ...` - `TiDB vX.Y.Z introduces ...` - `TiDB vX.Y.Z optimizes ...` -**Chinese** +Common Chinese openings: - `从 vX.Y.Z 开始，……` - `在 vX.Y.Z 中，……` - `TiDB vX.Y.Z 引入……` - `TiDB vX.Y.Z 优化了……` -The after paragraph answers: what the feature does, how it works (briefly), and what the user gains. +The paragraph should answer: -### Before-after structure examples +- What is the capability? +- How do users enable, configure, or use it, if applicable? +- What concrete benefit does it provide? -**Example 1: Problem → solution (v8.5.6, column-level privilege)** +## Optional details -```markdown -* Support column-level privilege management [#61706](...) @[CbcWestwolf](...) @[fzzf678](...) +Add extra details only when they help users evaluate or use the feature. - Before v8.5.6, TiDB privilege control covers the database and table levels and does not support granting or revoking privileges on specific columns, unlike MySQL. As a result, you cannot restrict users to access only a subset of sensitive columns in a table. - - Starting from v8.5.6, TiDB supports column-level privilege management. You can use the `GRANT` and `REVOKE` statements to manage privileges on specific columns. TiDB performs privilege checks based on column-level privileges during query processing and execution plan construction, enabling finer-grained access control and better support for sensitive data isolation and the principle of least privilege. - - For more information, see [documentation](...). -``` - -**Example 2: GA transition with version history (v8.5.0, schema cache)** - -```markdown -* Setting the memory limit for schema cache is now generally available (GA). When the number of tables reaches hundreds of thousands or even millions, this feature significantly reduces the memory usage of schema metadata [#50959](...) @[tiancaiamao](...) - - In some SaaS scenarios, where the number of tables reaches hundreds of thousands or even millions, schema metadata can consume a significant amount of memory. With this feature enabled, TiDB uses the Least Recently Used (LRU) algorithm to cache and evict the corresponding schema metadata, effectively reducing memory usage. - - Starting from v8.4.0, this feature is enabled by default with a default value of `536870912` (that is, 512 MiB). You can adjust it as needed using the variable [`tidb_schema_cache_size`](/system-variables.md#tidb_schema_cache_size-new-in-v800). - - For more information, see [documentation](/schema-cache.md). -``` - -**Example 3: New feature with performance benchmarks (v8.5.5, lossy DDL)** - -```markdown -* Introduce significant performance improvements for certain lossy DDL operations (...) [#63366](...) @[wjhuang2016](...) - - The optimization strategies are as follows: - - - In strict SQL mode, TiDB pre-checks for potential data truncation risks during type conversion. - - If no data truncation risk is detected, TiDB updates only the metadata and avoids index rebuilding whenever possible. - - If index rebuilding is required, TiDB uses a more efficient ingest process to significantly improve index rebuild performance. - - The following table shows example performance improvements based on benchmark tests ... - - | Scenario | Operation type | Before optimization | After optimization | Performance improvement | - |----------|----------------|---------------------|--------------------|--------------------------| - | Non-indexed column | `BIGINT → INT` | 2 hours 34 minutes | 1 minute 5 seconds | 142× faster | - | Indexed column | `BIGINT → INT` | 6 hours 25 minutes | 0.05 seconds | 460,000× faster | - | Indexed column | `CHAR(120) → VARCHAR(60)` | 7 hours 16 minutes | 12 minutes 56 seconds | 34× faster | - - Note that the preceding test results are based on the condition that no data truncation occurs ... - - For more information, see [documentation](...). -``` - -**Example 4: New architecture with caveats (v8.5.4, TiCDC architecture)** - -```markdown -* Introduce a new TiCDC architecture option for improved performance, scalability, and stability [#442](...) @[CharlesCheung96](...) - - This new architecture redesigns TiCDC core components and optimizes its data processing workflows, while maintaining compatibility with the configuration, usage, and APIs of the classic TiCDC architecture. - - When configured to use this new architecture, TiCDC achieves near-linear scalability and can replicate millions of tables with lower resource consumption. It also reduces changefeed latency and delivers more stable performance in scenarios with high write workloads, frequent DDL operations, and cluster scaling. Note that the new architecture currently has some initial limitations. - - To use the new architecture, set the TiCDC configuration item [`newarch`](...) to `true`. - - For more information, see [documentation](...). -``` - -### Additional details - -When extra context is needed, use one or more of the following patterns after the before-after paragraphs: - -- **Configuration or usage instructions**: describe how to enable, configure, or use the feature. Include variable names, configuration items, SQL statements, or command-line flags in backticks. -- **Performance benchmarks**: include a table or inline metrics when available. State the test conditions (cluster spec, data size). -- **Caveats and limitations**: describe restrictions, unsupported scenarios, or known issues. Use phrasing like `Note that ...` or a separate paragraph. -- **Sub-list of capabilities**: use `-` items indented under the main entry for enumerating sub-features, supported operations, or optimization strategies. -- **Behavior details**: describe behavior for different conditions (for example, "If X finishes before timeout, Y. If X does not finish, Z."). +- Configuration or usage: mention system variables, configuration items, SQL statements, command-line flags, and literal values in backticks. +- Caveats and limitations: state unsupported cases, disabled-by-default behavior, compatibility notes, or known constraints. +- Performance metrics: include the metric, magnitude, and test conditions when available. Do not use unsourced claims such as "significant" or "large" unless the input supports them. +- Sub-feature lists: use indented `-` items for supported operations, optimization strategies, or new fields. +- Benchmark tables: include only sourced results and enough environment details to make the numbers meaningful. ## Documentation link -Every feature entry ends with a documentation link. +End every complete feature description with a documentation link. -**English** +English: ```markdown For more information, see [documentation](/path-to-doc.md). - For more information, see [documentation](/path-to-doc.md#anchor). ``` -**Chinese** +Chinese: ```markdown 更多信息，请参考[用户文档](/path-to-doc.md)。 - 更多信息，请参考[用户文档](/path-to-doc.md#锚点)。 ``` -The documentation link is indented at the same level as the body paragraphs (4 spaces under the `*` title line). Both English and Chinese doc link lines end with a period (`.` for English, `。` for Chinese), because they are full sentences within body paragraphs. +If no documentation page exists yet, do not invent one. Ask for the intended documentation link or leave a clear placeholder for human follow-up. -## GA, experimental, and version-lifecycle language +## Maturity and version history -### GA features +For experimental features: -When a feature transitions to GA, the description should briefly mention its history: +- Add `(experimental)` to the title line. +- State whether the feature is disabled by default, and explain how to enable it if the input provides that information. -- `The foreign key feature becomes generally available (GA) in v8.5.0.` -- `Starting from v8.5.0, this feature becomes generally available (GA).` -- `In v8.2.0, this feature becomes generally available (GA) and is enabled by default.` -- `TiDB v7.6.0 introduces X as an experimental feature. ... In v8.5.0, this feature becomes generally available (GA).` +For features that become generally available (GA) from an experimental version: -Chinese equivalents: +- Add `(GA)` to the title line when it reads naturally. +- Mention the previous experimental version if known. +- State whether the feature becomes enabled by default if that is part of the release behavior. -- `外键功能在 v8.5.0 中正式 GA。` -- `从 v8.5.0 开始，该功能正式 GA。` +For features that are new and GA from the start: -### Experimental features +- No need to add `(GA)` to the title line, which means that a feature is GA by default if `(experimental)` is not present. -When a feature is introduced as experimental, state this clearly: +Useful patterns: -- `(experimental)` in the title tag -- `This feature is currently experimental and is disabled by default.` in the body (if applicable) - -### Version-history references +```markdown +TiDB vX.Y.Z introduces as an experimental feature. In vA.B.C, this feature becomes generally available (GA). -For features first introduced in an earlier version, mention the version history: +Starting from vA.B.C, becomes generally available (GA) and is enabled by default. +``` -- `TiDB v7.6.0 introduces X as an experimental feature, controlled by the system variable [`Y`](...). Starting from v8.0.0, this system variable is renamed to [`Z`](...).` -- `In v8.0.0, TiKV encryption at rest experimentally supports using Google Cloud KMS. Starting from v8.5.0, this feature becomes generally available (GA).` +Do not infer a maturity state from the PR alone. Use only information provided by the issue, PR, release plan, PM input, or existing documentation. ## Style rules -### Tone and perspective +- Write for users, not implementers. +- Prefer `you can ...`, `TiDB supports ...`, and `Starting from vX.Y.Z, ...`. +- State the capability or benefit before implementation details. +- Use present tense for product behavior. +- Use active voice when natural. +- Keep paragraphs short. Split long explanations into multiple paragraphs or a list. +- Do not expose internal function names, package names, test names, or code-level refactors unless they are user-visible. +- Do not overstate certainty. Use `can improve` or `helps reduce` when the benefit depends on workload. +- Use normal sentence punctuation in body paragraphs. Only the title line omits the trailing period. -- Write from the user's perspective. Describe what the user can do, what the user observes, or what changes for the user. -- Use present tense for describing the feature's behavior: "TiDB supports ...", "You can use ...". -- Use imperative mood for configuration instructions: "Set the variable to ...", "To enable this feature, ...". +Chinese-specific rules: -### Sentence structure +- Use full-width punctuation in Chinese prose: `，`、`。`、`（`、`）`、`：`. +- Use Chinese verbs that match release-note style: `支持`, `引入`, `提供`, `新增`, `提升`, `优化`, `加速`. +- The Chinese documentation link sentence ends with `。`. +- The Chinese title line does not end with `。`. -- Lead with the most important information. State the capability or benefit before describing the mechanism. -- Avoid passive voice when active voice is natural: prefer "TiDB supports X" over "X is supported by TiDB". -- Use concise compound sentences. Avoid overly long sentences; break complex descriptions into separate sentences. +## Examples -### Metric claims +### Standard before-and-after feature -Performance claims should include: +```markdown +* Support column-level privilege management [#61706](https://github.com/pingcap/tidb/issues/61706) @[CbcWestwolf](https://github.com/CbcWestwolf) @[fzzf678](https://github.com/fzzf678) -- The metric type (for example, "performance", "QPS", "latency") -- The magnitude (for example, "up to 25x", "by 62.5%", "from hours to seconds") -- The test conditions when available (cluster spec, data size) + Before v8.5.6, TiDB privilege control covers the database and table levels and does not support granting or revoking privileges on specific columns, unlike MySQL. As a result, you cannot restrict users to access only a subset of sensitive columns in a table. + + Starting from v8.5.6, TiDB supports column-level privilege management. You can use the `GRANT` and `REVOKE` statements to manage privileges on specific columns. TiDB performs privilege checks based on column-level privileges during query processing and execution plan construction, enabling finer-grained access control and better support for sensitive data isolation and the principle of least privilege. -### Trailing period convention + For more information, see [documentation](https://docs.pingcap.com/tidb/v8.5/column-privilege-management). +``` -Feature body paragraphs use normal sentence punctuation with trailing periods. Only the title line omits the trailing period. This differs from single-line improvement and bug-fix entries, which omit the trailing period entirely. +### Experimental feature with enablement -### Chinese-specific rules +```markdown +* Support table-level data affinity to improve query performance (experimental) [#9764](https://github.com/tikv/pd/issues/9764) @[lhy1024](https://github.com/lhy1024) -Chinese title lines follow the same verb patterns as English but use Chinese verbs: + Starting from v8.5.5, you can configure the `AFFINITY` table option as `table` or `partition` when creating or altering a table. When this option is enabled, PD groups Regions that belong to the same table or partition into a single affinity group and prioritizes placing their Leaders and Voter replicas on the same subset of TiKV nodes. This reduces latency caused by cross-node scattered queries and can improve query performance. -| English verb | Chinese equivalent | -|-------------|-------------------| -| `Support` | `支持` | -| `Introduce` | `引入` | -| `Provide` | `提供` | -| `Add` | `新增` | -| `Improve` | `提升` / `优化` | -| `Accelerate` | `加速` | + Note that this feature is currently experimental and is disabled by default. To enable it, set the PD configuration item `schedule.affinity-schedule-limit` to a value greater than `0`. -Before-after phrasing: + For more information, see [documentation](https://docs.pingcap.com/tidb/v8.5/table-affinity). +``` -- Before: `在 vX.Y.Z 之前，……` / `在此前版本中，……` -- After: `从 vX.Y.Z 开始，……` / `TiDB vX.Y.Z 引入了……` +### GA transition -Punctuation: +```markdown +* Provide the Active PD Follower feature to enhance the scalability of PD's Region information query service (GA) [#7431](https://github.com/tikv/pd/issues/7431) @[okJiang](https://github.com/okJiang) -- Use full-width punctuation in Chinese prose: `，`、`。`、`（`、`）`、`：` -- Documentation link sentence ends with `。`: `更多信息，请参考[用户文档](/path.md)。` -- Title lines do not end with `。` + In a TiDB cluster with a large number of Regions, the PD leader might experience high CPU load due to the increased overhead of handling heartbeats and scheduling tasks. If the cluster has many TiDB instances and a high concurrency of Region information requests, the CPU pressure on the PD leader increases further and might cause PD services to become unavailable. -## Differences between major and patch releases + TiDB v7.6.0 introduces Active PD Follower as an experimental feature. In v8.5.0, this feature becomes generally available (GA). After this feature is enabled, TiDB evenly distributes Region information requests to all PD servers, and PD followers can also handle Region requests, thereby reducing the CPU pressure on the PD leader. -| Aspect | Major/DMR release | Patch release | -|--------|-------------------|---------------| -| Section heading | `## Feature details` | `## Features` | -| Level-3 category headings | Always present | Present when there are enough features; may be omitted for a small number of features | -| Highlight table | Major releases may include an HTML `
` summary of highlights at the top of the file, before `## Feature details` | Not present | -| Scope | New features, GA transitions, and major capability additions | Backported features, GA transitions, and incremental capability additions | -| Version-history detail | More detailed for features that evolved over multiple DMR cycles | Typically shorter; references the original introduction version | + For more information, see [documentation](/tune-region-performance.md#use-the-active-pd-follower-feature-to-enhance-the-scalability-of-pds-region-information-query-service). +``` -## Common review findings +## Review checklist -| Finding | Correct | -|---------|---------| -| Entry uses `-` instead of `*` for the title line | Use `*` for the feature title line (sub-items within the body use `-`) | -| Missing before paragraph for a feature that addresses a pre-existing limitation | Add a before paragraph describing the limitation or pain point | -| Missing documentation link | Add `For more information, see [documentation](/path.md).` | -| Title line ends with `.` | Remove the trailing period from the title line | -| Body omits the version number in `Starting from ...` | Always specify the version: `Starting from v8.5.5, ...` | -| GA transition does not mention the original experimental version | Add version history: `Introduced as experimental in vX.Y.Z.` | -| Feature description only explains what the code does, not the user benefit | Rewrite to explain what the user gains (capability, performance, stability) | -| Chinese doc link missing `。` | Chinese doc link line ends with `。`: `更多信息，请参考[用户文档](/path.md)。` | -| English doc link missing `.` | English doc link line ends with `.`: `For more information, see [documentation](/path.md).` | -| Performance claim without test conditions | Add test environment details (cluster spec, data size) when available | -| Maturity tag missing for experimental features | Add `(experimental)` to the title | -| Maturity tag missing for GA transitions | Add `(GA)` or `(GA in vX.Y.Z)` to the title | -| Chinese anchor uses English suffix | Change `-new-in-vXYZ` to `-从-vXYZ-版本开始引入` in Chinese entries | -| Inline code not applied to variables, configs, or SQL keywords | Apply backtick formatting per the inline-code rules in SKILL.md | +- The entry describes user-facing capability and value, not only implementation work. +- The title line is concise, has issue and contributor links, and has no trailing period. +- Existing limitations are explained when needed. +- Enablement, configuration, caveats, and limitations are included when relevant. +- Performance claims include metrics and test conditions when available. +- Variables, config parameters, SQL statements, error messages, literal values, and links use the formatting rules in [SKILL.md](../SKILL.md). +- The entry ends with a valid documentation link or an explicit placeholder for follow-up. +- The wording follows nearby release note entries in the target file.