From 30a3d9ace364dd2a639540855cf3f6f983efced7 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 17 Jul 2026 16:36:36 +0800 Subject: [PATCH 1/6] add .coderabbit.yaml --- .ai/shared/review-style.md | 71 ++++++++++++++++++++++++++++++++++++++ .coderabbit.yaml | 29 ++++++++++++++++ 2 files changed, 100 insertions(+) create mode 100644 .ai/shared/review-style.md create mode 100644 .coderabbit.yaml diff --git a/.ai/shared/review-style.md b/.ai/shared/review-style.md new file mode 100644 index 0000000000000..0eca61ea5f9a1 --- /dev/null +++ b/.ai/shared/review-style.md @@ -0,0 +1,71 @@ +# Documentation Review Style Guide + +## Behavior instruction + +You are acting as a **senior technical writer** who is reviewing TiDB documentation pull requests and you always provide ready-to-commit doc suggestions so the PR author can commit them directly. + +## Note + +When you finish the review, you directly add comments to the PR instead of requesting changes to avoid blocking the pull request from being merged. + +## Review aspects + +- Clarity, simplicity, completeness, and readability +- Logical flow and sentence structure +- Technical accuracy and terminology consistency + +## General writing principles + +- Correct English grammar, spelling, and punctuation mistakes, if any. +- Make sure the documentation is easy to understand for TiDB users. +- Write in **second person** ("you") when addressing users. +- Prefer **present tense** unless describing historical behavior. +- Avoid unnecessary words and repetition. +- Use **consistent terminology**. For example: + + - ❌ Do not mix "database" and "instance" + - ✅ Use "replicate" instead of "synchronize" when referring to replicating data from one TiDB cluster to another. + +## Structure and format + +- Use title case for 1st-level headings (e.g., `# Configure the cluster`). +- Use sentence case for 2nd-level and other lower-level headings (e.g., `## Configure the cluster`). +- Use ordered lists (`1.`, `2.`) for steps. +- Code snippets, command names, options, and paths should be in backticks (`` ` ``). + +## Markdown style + +- Add a blank line before and after headings and lists. +- Use proper heading hierarchy (no jumping from `##` to `####`). + +## Common issues to flag + +- Passive voice overuse + + _"The cluster is started by TiUP"_ → _"TiUP starts the cluster"_ + +- Inconsistent use of technical terms + + _"TiDB Cloud Starter instances" vs. "TiDB Starter instances"_ – pick one. + +- Incorrect MySQL version notation + + Use `MySQL 8.0`, `MySQL 8.4`, or `MySQL 8.x`. Do not use `MySQL v8.0`. The `v` prefix is reserved for TiDB and TiDB-tool versions (for example, `TiDB v8.5` and `DM v2.0`). _"MySQL v8.0"_ → _"MySQL 8.0"_. + +- Unclear step instructions + + _"Do it like before"_ → _"Repeat step 3 using the updated config file"_ + +- Grammar and spelling issues + + _"recieve"_ → _"receive"_, _"an TiDB instance"_ → _"a TiDB instance"_ + +## Special notes + +- Follow any existing terminology in our glossary (`/glossary.md` if available). +- When in doubt, favor clarity over cleverness. +- If something might confuse a new user, suggest a reword. + +## Purposes of this style guide + +This guide helps AI-powered tools provide actionable, high-quality suggestions for improving technical documentation, especially for PRs related to user guides, how-to articles, and product reference material. diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 0000000000000..218006863ee47 --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,29 @@ +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json + +language: en-US +early_access: false + +reviews: + # Preserve the LOW severity threshold so documentation wording, grammar, spelling, and punctuation are reviewed. + profile: assertive + request_changes_workflow: false + poem: false + in_progress_fortune: false + + auto_review: + enabled: true + drafts: false + # CodeRabbit always includes the default branch. Keep target branches explicit so auto review remains enabled even if the default branch changes. + base_branches: + - '^master$' + - '^release-8\.5$' + +knowledge_base: + code_guidelines: + enabled: true + filePatterns: + - files: .ai/shared/review-style.md + applyTo: '**/*.md' + +chat: + art: false From 8ac07da2bf85a5d88ba8c704314381b54c92cafc Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 17 Jul 2026 17:53:46 +0800 Subject: [PATCH 2/6] use writing-style.md for .coderabbit.yaml --- .agents/shared/review-style.md | 71 --------------------------------- .agents/shared/writing-style.md | 33 ++++++++++----- .coderabbit.yaml | 10 ++++- 3 files changed, 32 insertions(+), 82 deletions(-) delete mode 100644 .agents/shared/review-style.md diff --git a/.agents/shared/review-style.md b/.agents/shared/review-style.md deleted file mode 100644 index 0eca61ea5f9a1..0000000000000 --- a/.agents/shared/review-style.md +++ /dev/null @@ -1,71 +0,0 @@ -# Documentation Review Style Guide - -## Behavior instruction - -You are acting as a **senior technical writer** who is reviewing TiDB documentation pull requests and you always provide ready-to-commit doc suggestions so the PR author can commit them directly. - -## Note - -When you finish the review, you directly add comments to the PR instead of requesting changes to avoid blocking the pull request from being merged. - -## Review aspects - -- Clarity, simplicity, completeness, and readability -- Logical flow and sentence structure -- Technical accuracy and terminology consistency - -## General writing principles - -- Correct English grammar, spelling, and punctuation mistakes, if any. -- Make sure the documentation is easy to understand for TiDB users. -- Write in **second person** ("you") when addressing users. -- Prefer **present tense** unless describing historical behavior. -- Avoid unnecessary words and repetition. -- Use **consistent terminology**. For example: - - - ❌ Do not mix "database" and "instance" - - ✅ Use "replicate" instead of "synchronize" when referring to replicating data from one TiDB cluster to another. - -## Structure and format - -- Use title case for 1st-level headings (e.g., `# Configure the cluster`). -- Use sentence case for 2nd-level and other lower-level headings (e.g., `## Configure the cluster`). -- Use ordered lists (`1.`, `2.`) for steps. -- Code snippets, command names, options, and paths should be in backticks (`` ` ``). - -## Markdown style - -- Add a blank line before and after headings and lists. -- Use proper heading hierarchy (no jumping from `##` to `####`). - -## Common issues to flag - -- Passive voice overuse - - _"The cluster is started by TiUP"_ → _"TiUP starts the cluster"_ - -- Inconsistent use of technical terms - - _"TiDB Cloud Starter instances" vs. "TiDB Starter instances"_ – pick one. - -- Incorrect MySQL version notation - - Use `MySQL 8.0`, `MySQL 8.4`, or `MySQL 8.x`. Do not use `MySQL v8.0`. The `v` prefix is reserved for TiDB and TiDB-tool versions (for example, `TiDB v8.5` and `DM v2.0`). _"MySQL v8.0"_ → _"MySQL 8.0"_. - -- Unclear step instructions - - _"Do it like before"_ → _"Repeat step 3 using the updated config file"_ - -- Grammar and spelling issues - - _"recieve"_ → _"receive"_, _"an TiDB instance"_ → _"a TiDB instance"_ - -## Special notes - -- Follow any existing terminology in our glossary (`/glossary.md` if available). -- When in doubt, favor clarity over cleverness. -- If something might confuse a new user, suggest a reword. - -## Purposes of this style guide - -This guide helps AI-powered tools provide actionable, high-quality suggestions for improving technical documentation, especially for PRs related to user guides, how-to articles, and product reference material. diff --git a/.agents/shared/writing-style.md b/.agents/shared/writing-style.md index bb609c3e5868a..5633f3a7a0939 100644 --- a/.agents/shared/writing-style.md +++ b/.agents/shared/writing-style.md @@ -5,8 +5,10 @@ Use this guidance for authoring, editing, or reviewing Markdown in `pingcap/docs ## Overall principles - Write for TiDB users, not for internal teams. -- Use a conversational and friendly tone, but do not sound casual, playful, or promotional. +- Use a conversational and friendly tone, but do not sound playful or promotional. - Prefer clear, direct, and practical language. +- When in doubt, favor clarity over cleverness. +- Rewrite content that might confuse a new user. - Do not pre-announce what the document will do. Start with useful information directly. - Write for a global audience. Avoid culture-specific references, vague shorthand, and region-specific assumptions. - Write accessibly. Prefer simple sentence structures and wording that is easy to scan and understand. @@ -25,12 +27,21 @@ Use this guidance for authoring, editing, or reviewing Markdown in `pingcap/docs - Use second person, such as `you` and `your`, instead of `we`. - Use active voice whenever possible. Make it clear who performs the action. +- Prefer present tense unless you are describing historical behavior. +- Correct English grammar, spelling, and punctuation errors. - Put conditions before instructions, not after. - Use standard American English spelling and punctuation. - Use serial commas. - Prefer concise and precise wording over decorative phrasing. - Preserve technical meaning. Do not rewrite in ways that change product behavior or scope. +## Terminology and version notation + +- Use terminology consistently. Do not use "database" and "instance" interchangeably. Choose the term that matches the actual product concept. +- Use "replicate" instead of "synchronize" when referring to replicating data from one TiDB cluster to another. +- Write MySQL versions as `MySQL 8.0`, `MySQL 8.4`, or `MySQL 8.x`. Do not add a `v` prefix. The `v` prefix is reserved for TiDB and TiDB tool versions, such as `TiDB v8.5` and `DM v2.0`. +- Follow the established terminology in `glossary.md` and `resources/terms.md`. + ## Structure and organization - Keep the structure easy to scan with meaningful headings and short paragraphs. @@ -100,14 +111,16 @@ Keep the frontmatter `title` and the H1 aligned in wording and capitalization. - Use images only when they add value that text alone cannot provide. - Keep screenshots and diagrams aligned with the current product behavior and UI text. -## Review lens - -When reviewing or rewriting content, check these in order: +## Final checklist -1. Is the content factually correct? -2. Is the logic complete and easy to follow? -3. Are other related documents also affected and likely to need updates? -4. Does the structure match the document type? -5. Does the wording improve clarity without changing product meaning? +Before finalizing authored, edited, or reviewed content, verify that: -Make feedback specific, actionable, and tied to the changed content. Avoid praise-only edits. +- [ ] The content addresses a clear user need and is appropriate for its intended audience. +- [ ] Technical facts are accurate, and edits preserve the intended product behavior and scope. +- [ ] The structure matches the document type, and headings follow the required hierarchy and capitalization. +- [ ] Procedures present prerequisites and conditions before clear, actionable steps. +- [ ] Terminology, product names, and version notation are accurate and consistent. +- [ ] Commands, code, configuration names, API fields, UI strings, and literal values remain correct. +- [ ] Links, formatting, lists, notes, warnings, images, and alt text follow repository conventions. +- [ ] The language is clear, concise, grammatically correct, and easy for a global audience to understand. +- [ ] Related documents, TOC entries, aliases, or cross-references have been considered when applicable. diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 409e2fa98177e..8d8354d9b6c12 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -18,11 +18,19 @@ reviews: - '^master$' - '^release-8\.5$' + path_instructions: + - path: '**/*.md' + instructions: | + - Act as a senior technical writer when reviewing documentation. + - Provide ready-to-commit suggestions that PR authors can apply directly. + - Post regular review comments instead of requesting changes so the review does not block the PR from being merged. + - Make feedback specific, actionable, and tied to the changed content. Avoid praise-only edits. + knowledge_base: code_guidelines: enabled: true filePatterns: - - files: .agents/shared/review-style.md + - files: .agents/shared/writing-style.md applyTo: '**/*.md' chat: From 3702fd80f6d73cd25c932c58845ef112bf64dd19 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 17 Jul 2026 19:58:39 +0800 Subject: [PATCH 3/6] Apply suggestions from code review --- .coderabbit.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 8d8354d9b6c12..3bd1441581fe9 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -4,7 +4,6 @@ language: en-US early_access: false reviews: - # Preserve the LOW severity threshold so documentation wording, grammar, spelling, and punctuation are reviewed. profile: assertive request_changes_workflow: false poem: false From 96861e266852f2d77e1a270fe37ff384372af981 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 17 Jul 2026 20:02:29 +0800 Subject: [PATCH 4/6] Update .coderabbit.yaml --- .coderabbit.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 3bd1441581fe9..3e13c32a03ea1 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -11,6 +11,8 @@ reviews: auto_review: enabled: true + auto_incremental_review: true + auto_pause_after_reviewed_commits: 2 drafts: false # CodeRabbit always includes the default branch. Keep target branches explicit so auto review remains enabled even if the default branch changes. base_branches: From 2209a2d10a26b19d3f5a7176d38c1c11ceeac925 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 17 Jul 2026 20:15:57 +0800 Subject: [PATCH 5/6] Update .coderabbit.yaml --- .coderabbit.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 3e13c32a03ea1..f49885d3d6390 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -24,7 +24,6 @@ reviews: instructions: | - Act as a senior technical writer when reviewing documentation. - Provide ready-to-commit suggestions that PR authors can apply directly. - - Post regular review comments instead of requesting changes so the review does not block the PR from being merged. - Make feedback specific, actionable, and tied to the changed content. Avoid praise-only edits. knowledge_base: From 2e92fa33b4f4e9a9da8ad85252d4055b710f9feb Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 17 Jul 2026 20:26:15 +0800 Subject: [PATCH 6/6] Apply suggestions from code review --- .coderabbit.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index f49885d3d6390..31de3c74d4b73 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -3,7 +3,12 @@ language: en-US early_access: false +# Controls how comments are written, not how many comments are posted. +tone_instructions: >- + Be concise, direct, and professional. Avoid praise, filler, and subjective style preferences. + reviews: + # Keep assertive to catch language, clarity, and consistency issues. profile: assertive request_changes_workflow: false poem: false @@ -24,7 +29,7 @@ reviews: instructions: | - Act as a senior technical writer when reviewing documentation. - Provide ready-to-commit suggestions that PR authors can apply directly. - - Make feedback specific, actionable, and tied to the changed content. Avoid praise-only edits. + - Make feedback specific, actionable, and tied to the changed content. Avoid praise-only comments, summaries of correct content, duplicate comments, broad rewrites, and low-value nitpicks. knowledge_base: code_guidelines: