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
missing-translation-status
Oreoxmt
changed the title
![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 new AI skill, writing-doc-summaries, which provides guidelines and a workflow for generating SEO-friendly front matter summaries in Markdown files. The skill includes specific rules for character counts, opening verbs, and YAML formatting. Review feedback focused on maintaining terminology consistency by using "front matter" as two words, adhering to the repository's style guide for sentence-case headings, ensuring field names are wrapped in backticks, and adding a trailing newline to the new skill file.
.ai/AI-README.md
Outdated
|
|
||
| - `.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` frontmatter field in a document following the repo's 115–145 character SEO-friendly sentence rules |
There was a problem hiding this comment.
Use "front matter" (two words) for consistency with line 15 of this file and general repository conventions.
| - `.ai/skills/writing-doc-summaries/`: write or update the `summary` frontmatter field in a document following the repo's 115–145 character SEO-friendly sentence rules | |
| - .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 |
|
|
||
| Write or improve the `summary` field in the YAML frontmatter of Markdown files in `pingcap/docs` and `pingcap/docs-cn`. | ||
|
|
||
| ## frontmatter example |
There was a problem hiding this comment.
Use sentence case for headings and use "front matter" (two words) for consistency with the repository's README.
| ## frontmatter example | |
| ## Front matter example |
References
- Use sentence case for headings (e.g., ## Configure the cluster). (link)
| - If frontmatter exists, update the `summary` line in place. | ||
| - If frontmatter is missing, add it at the top: |
There was a problem hiding this comment.
Use "front matter" (two words) instead of "frontmatter" for consistency. Also, enclose the field name summary in backticks.
| - If frontmatter exists, update the `summary` line in place. | |
| - If frontmatter is missing, add it at the top: | |
| - If front matter exists, update the `summary` line in place. | |
| - If front matter is missing, add it at the top: |
References
- Code snippets, command names, options, and paths should be in backticks. (link)
| - Do not rewrite or reformat any other part of the document. | ||
|
|
||
| ## Gut check | ||
|
|
There was a problem hiding this comment.
Add a newline at the end of the file to follow standard POSIX conventions.
| Before applying: **would this make a TiDB user want to click through from search results?** If not, rewrite. | |
ti-chi-bot
bot
removed
the
missing-translation-status
|
@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. |
| ```yaml | ||
| --- | ||
| title: Back up and Restore Data Using Dumpling and TiDB Lightning | ||
| summary: Learn how to use Dumpling and TiDB Lightning to back up and restore full data of TiDB. |
There was a problem hiding this comment.
This summary is below the 115-character minimum stated in Rule 1. Perhaps we could change the length range or update this example.
| 1. **Length**: 115-145 characters including spaces. | ||
| 2. **Opening verb**: Start with an SEO-friendly verb phrase (see table below) that tells the reader what they will get from this document. Never start with the document title, a product name alone, or a noun phrase. | ||
| 3. **Perspective**: Reader-focused — tell them what they will learn or do. | ||
| 4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. |
There was a problem hiding this comment.
| 4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. | |
| 4. **No special leading characters**: Do not start with `>`, `*`, `#`, `-`, or `[`. If the summary must begin with a special character, wrap the entire value in quotation marks. |
| **After** (introduces concept and explains why it matters): | ||
|
|
||
| ```yaml | ||
| summary: Introduce the concept, principles, and implementation of metadata lock in TiDB, and learn how it prevents DDL and DML conflicts. |
There was a problem hiding this comment.
| summary: Introduce the concept, principles, and implementation of metadata lock in TiDB, and learn how it prevents DDL and DML conflicts. | |
| summary: Learn about the concept, principles, and implementation of metadata lock in TiDB, and understand how it prevents DDL and DML conflicts. |
There was a problem hiding this comment.
reason: "Introduce" is document-focused (the document introduces something), while "learn how" is reader-focused (the reader learns). This switches perspective mid-sentence, which conflicts with Rule 3: "Reader-focused — tell them what they will learn or do."
|
|
||
| Scan a few existing summaries in the same subdirectory first to match local conventions. | ||
|
|
||
| ### Preferred patterns |
There was a problem hiding this comment.
If this skill is for both pingcap/docs and pingcap/docs-cn, we might also include some examples in Chinese?
| ## Summary rules | ||
|
|
||
| 1. **Length**: 115-145 characters including spaces. | ||
| 2. **Opening verb**: Start with an SEO-friendly verb phrase (see table below) that tells the reader what they will get from this document. Never start with the document title, a product name alone, or a noun phrase. |
There was a problem hiding this comment.
"See table below" is vague, as the table is several sections away under "## Opening verb guidance".
|
|
||
| **Exceptions:** | ||
|
|
||
| - **SQL statement reference**: Use fixed template — `An overview of the usage of <STATEMENT> for the TiDB database`. No outcome clause needed. |
There was a problem hiding this comment.
Same here. This summary is below the 115-character minimum stated in Rule 1.
[LGTM Timeline notifier]Timeline:
|
2 participants
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?