Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
bot
added
the
size/XXL
|
@Oreoxmt: The following test failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive AI skill for writing, reviewing, and translating TiDB release notes, including detailed reference guides for bug fixes, improvements, and compatibility changes. The documentation establishes strict style rules for both English and Chinese content, such as specific opening verbs, inline code conventions, and bilingual alignment workflows. The review feedback focuses on improving the clarity and directness of these instructions by adhering to the style guide's preference for active voice and second-person address.
|
|
||
| - Each English section must have an exact Chinese counterpart. | ||
| - Example: If the English file has `### Behavior changes`, the Chinese file must have `### 行为变更`. | ||
| - Missing sections are considered defects. See SKILL.md for section heading mappings. |
There was a problem hiding this comment.
Use active voice to improve clarity and follow the style guide's preference for direct instructions.
| - Missing sections are considered defects. See SKILL.md for section heading mappings. | |
| - Treat missing sections as defects. See SKILL.md for section heading mappings. |
References
- Avoid passive voice overuse. (link)
| - Improvement: `[Action verb] [what was improved, added, or supported] [#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) @[contributor](https://github.com/contributor)` | ||
| 4. Draft the Chinese entry with the matching pattern | ||
| 5. Verify issue numbers match exactly between English and Chinese | ||
| 6. Verify anchor suffix format if doc links are included |
There was a problem hiding this comment.
Use active voice and address the user directly as 'you' to maintain consistency with the style guide.
| 6. Verify anchor suffix format if doc links are included | |
| 6. Verify the anchor suffix format if you include documentation links |
|
|
||
| ## English style rules | ||
|
|
||
| Lead with a fix verb phrase. The accepted patterns, listed roughly by frequency in published v6.1+ notes: |
There was a problem hiding this comment.
Rephrase to use active voice for a more direct and professional tone.
| Lead with a fix verb phrase. The accepted patterns, listed roughly by frequency in published v6.1+ notes: | |
| Lead with a fix verb phrase. Use the following accepted patterns, which are listed roughly by frequency in published v6.1+ notes: |
References
- Avoid passive voice overuse. (link)
| * `修复 [X] 的问题` (most common) | ||
| * `修复 [X] 可能 [崩溃/panic/卡住/报错] 的问题` (non-deterministic failures) | ||
| * `修复 [X] 导致 [Y] 的问题` (cause-effect issues) | ||
| * `禁止 [X]` (used when the fix introduces a restriction rather than a repair; rare) |
There was a problem hiding this comment.
Use active voice in the parenthetical instruction to follow the style guide.
| * `禁止 [X]` (used when the fix introduces a restriction rather than a repair; rare) | |
| * 禁止 [X] (Use this when the fix introduces a restriction rather than a repair; rare) |
References
- Avoid passive voice overuse. (link)
|
|
||
| ## Behavior changes | ||
|
|
||
| Each behavior change is written as a paragraph, not a table row. A complete entry must include: |
There was a problem hiding this comment.
Use active voice to provide clear, direct instructions to the user.
| Each behavior change is written as a paragraph, not a table row. A complete entry must include: | |
| Write each behavior change as a paragraph, not a table row. A complete entry must include: |
References
- Avoid passive voice overuse. (link)
| 3. The reason for the change (optional but recommended for significant changes) | ||
| 4. A documentation link: "For more information, see [documentation](/path.md#anchor)." / "更多信息，请参考[用户文档](/path.md#锚点)。" | ||
|
|
||
| Omitting either the old behavior or the new behavior is considered a defect. |
There was a problem hiding this comment.
Rephrase to active voice to improve the strength of the instruction.
| Omitting either the old behavior or the new behavior is considered a defect. | |
| Treat the omission of either the old behavior or the new behavior as a defect. |
References
- Avoid passive voice overuse. (link)
|
|
||
| ### Anchor suffix convention | ||
|
|
||
| For variables introduced in this version, the documentation anchor includes a version suffix: |
There was a problem hiding this comment.
Use active voice and address the user directly to follow the style guide.
| For variables introduced in this version, the documentation anchor includes a version suffix: | |
| For variables that you introduce in this version, include a version suffix in the documentation anchor: |
| - Entry [#NNNNN](https://github.com/pingcap/tidb/issues/NNNNN) @[contributor](https://github.com/contributor) | ||
| ``` | ||
|
|
||
| Component groups use `+`, and individual entries use `-`. Tools are nested one level deeper under `+ Tools`. |
There was a problem hiding this comment.
Use active voice for the instruction regarding nesting tools.
| Component groups use `+`, and individual entries use `-`. Tools are nested one level deeper under `+ Tools`. | |
| Component groups use `+`, and individual entries use `-`. Nest tools one level deeper under `+ Tools`. |
References
- Avoid passive voice overuse. (link)
|
|
||
| State the user benefit explicitly. Explain why the change matters in terms of performance, stability, or capability. For example, instead of "Not use the stale read request's `start_ts` to update `max_ts`," write "Avoid excessive commit request retrying by not using the Stale Read request's `start_ts` to update `max_ts`." | ||
|
|
||
| Metric claims are encouraged when sourced, such as "up to 10 times performance improvement" or "improves performance by up to 62.5%." |
There was a problem hiding this comment.
Use active voice and address the user directly to encourage best practices.
| Metric claims are encouraged when sourced, such as "up to 10 times performance improvement" or "improves performance by up to 62.5%." | |
| Encourage metric claims when you have a source, such as "up to 10 times performance improvement" or "improves performance by up to 62.5%." |
1 participant
First-time contributors' checklist
What is changed, added or deleted? (Required)
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?