diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 09a8ee327fac0..a7ce766951279 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 - `.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 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..1f8d640a121ad --- /dev/null +++ b/.ai/skills/write-review-translate-release-notes/references/feature-description.md @@ -0,0 +1,258 @@ +# Feature descriptions + +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. + +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. + +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 + +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. + +## Section placement in the release note file + +```markdown +## Features +``` + +Use level-3 category headings when the release groups features by area. Common categories are: + +- `### Scalability` +- `### Performance` +- `### Reliability` +- `### Availability` +- `### SQL` +- `### DB Operations and Observability` +- `### DB operations` +- `### Observability` +- `### Security` +- `### Data Migration` + +For Chinese heading mappings, see [SKILL.md](../SKILL.md). + +When writing the description for a feature, consider which category the feature belongs to and use the appropriate heading. + +## Entry shape + +Prefer this shape for a complete feature description: + +```markdown +* [#NNNNN](https://github.com/org/repo/issues/NNNNN) @[contributor](https://github.com/contributor) + + Before vX.Y.Z, . + + Starting from vX.Y.Z, . + + + + For more information, see [documentation](/path-to-doc.md). +``` + +Minimum viable entry: + +- Title line +- One paragraph that states the new behavior and user value +- Documentation link + +Add a before paragraph when the feature solves a known limitation, changes an existing workflow, or needs motivation to be understandable. + +## Title line + +The title line should name the capability and, when useful, include the main benefit. It is usually a verb phrase. + +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](...) +``` + +Title rules: + +- 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 + +### Context paragraph + +Use the context paragraph to explain why the feature matters. It usually describes the previous limitation or user scenario. + +Common English openings: + +- `Before vX.Y.Z, ...` +- `In TiDB versions earlier than vX.Y.Z, ...` +- `In earlier versions, ...` +- `.` + +Common Chinese openings: + +- `在 vX.Y.Z 之前，……` +- `在 vX.Y.Z 之前的版本中，……` +- `在此前版本中，……` + +### New behavior paragraph + +Use the new behavior paragraph to explain what changes in this version and what users gain. + +Common English openings: + +- `Starting from vX.Y.Z, ...` +- `In vX.Y.Z, ...` +- `TiDB vX.Y.Z introduces ...` +- `TiDB vX.Y.Z optimizes ...` + +Common Chinese openings: + +- `从 vX.Y.Z 开始，……` +- `在 vX.Y.Z 中，……` +- `TiDB vX.Y.Z 引入……` +- `TiDB vX.Y.Z 优化了……` + +The paragraph should answer: + +- What is the capability? +- How do users enable, configure, or use it, if applicable? +- What concrete benefit does it provide? + +## Optional details + +Add extra details only when they help users evaluate or use the feature. + +- 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 + +End every complete feature description with a documentation link. + +English: + +```markdown + For more information, see [documentation](/path-to-doc.md). +``` + +Chinese: + +```markdown + 更多信息，请参考[用户文档](/path-to-doc.md)。 +``` + +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. + +## Maturity and version history + +For experimental features: + +- 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. + +For features that become generally available (GA) from an experimental version: + +- 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. + +For features that are new and GA from the start: + +- No need to add `(GA)` to the title line, which means that a feature is GA by default if `(experimental)` is not present. + +Useful patterns: + +```markdown +TiDB vX.Y.Z introduces as an experimental feature. In vA.B.C, this feature becomes generally available (GA). + +Starting from vA.B.C, becomes generally available (GA) and is enabled by default. +``` + +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 + +- 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. + +Chinese-specific rules: + +- 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 `。`. + +## Examples + +### Standard before-and-after feature + +```markdown +* Support column-level privilege management [#61706](https://github.com/pingcap/tidb/issues/61706) @[CbcWestwolf](https://github.com/CbcWestwolf) @[fzzf678](https://github.com/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](https://docs.pingcap.com/tidb/v8.5/column-privilege-management). +``` + +### Experimental feature with enablement + +```markdown +* Support table-level data affinity to improve query performance (experimental) [#9764](https://github.com/tikv/pd/issues/9764) @[lhy1024](https://github.com/lhy1024) + + 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. + + 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`. + + For more information, see [documentation](https://docs.pingcap.com/tidb/v8.5/table-affinity). +``` + +### GA transition + +```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) + + 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. + + 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. + + 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). +``` + +## Review checklist + +- 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. 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