From 92db59a4191d7c964e75e45f3ca21dea74259575 Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 11 Jun 2026 23:39:45 +0800 Subject: [PATCH 1/4] add pr/issue metadate guard skills --- .ai/AI-README.md | 2 + .ai/skills/docs-issue-metadata-guard/SKILL.md | 117 ++++++++++++++++++ .ai/skills/docs-pr-metadata-guard/SKILL.md | 85 +++++++++++++ AGENTS.md | 2 + 4 files changed, 206 insertions(+) create mode 100644 .ai/skills/docs-issue-metadata-guard/SKILL.md create mode 100644 .ai/skills/docs-pr-metadata-guard/SKILL.md diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 45802a018e4f3..94336b68c91f0 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -25,6 +25,8 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui - `.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/docs-pr-metadata-guard/`: guard PR template structure when creating or editing pull requests — 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 — template selection, required fields, scope boundaries, and label hygiene The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for: diff --git a/.ai/skills/docs-issue-metadata-guard/SKILL.md b/.ai/skills/docs-issue-metadata-guard/SKILL.md new file mode 100644 index 0000000000000..dceed5ff6c5e5 --- /dev/null +++ b/.ai/skills/docs-issue-metadata-guard/SKILL.md @@ -0,0 +1,117 @@ +--- +name: docs-issue-metadata-guard +description: Use when creating or editing GitHub issues in pingcap/docs so issue templates, required fields, scope boundaries, and labels stay consistent with repository workflow. Trigger on tasks involving issue creation, error reports, change requests, questions, label selection, or searching for existing issues before filing a new one. +--- + +# Docs Issue Metadata Guard + +## Overview + +Use this skill for `pingcap/docs` GitHub issue metadata work. +The goal is to preserve issue-template structure, scope discipline, and searchable issue descriptions. + +Before creating or editing an issue, read the matching file under `.github/ISSUE_TEMPLATE/`. + +This repository has three issue templates and disables blank issues (`blank_issues_enabled: false` in `config.yml`). Every new issue must use one of the templates. + +## Issue Templates + +| Template | File | Use when | +|---|---|---| +| Error Report | `error-report.md` | Typos, grammatical errors, terminology misuse, ambiguity, broken formatting, incorrect code samples, wrong links | +| Change Request | `change-request.md` | Suggesting new content, restructuring, adding missing information, improving existing documentation | +| Question | `question.md` | Usage questions about documentation that are not answered in existing docs or discussions | + +## Scope Boundary + +All three templates include the same scope reminder: + +> This repository is ONLY used to solve issues related to DOCS. + +Enforce this boundary: + +- Do not file product bug reports, feature requests, or technical support questions in this repository. +- Redirect product issues to the appropriate repository under `github.com/pingcap/`. +- Redirect technical support questions to the TiDB community channels (Discord, Slack). +- If an issue mixes a doc problem with a product problem, separate them: file the doc part here and note where the product part should go. + +## Workflow + +1. Write issue titles and descriptions in English. +2. Search existing issues first before filing a new one. + - Check open and closed issues for duplicates or related discussions. + - If an existing issue covers the same problem, comment on it instead of creating a new one. +3. Choose the correct issue template based on the issue type. + - Do not write the body from scratch. Start from the matching template. + - The repository disables blank issues, but `gh issue create` does not enforce this — the agent must self-enforce template usage. +4. When using `gh issue create`: + - Use `--template "Error Report"`, `--template "Change Request"`, or `--template "Question"` to select the template (the `-T` / `--template` flag for `gh issue create` takes a template **name**, not a file path). + - Alternatively, copy the template body (everything below the YAML front matter `---` block) into a local file and use `--body-file `. The YAML front matter (`name:` and `about:`) is GitHub metadata and does not appear in the issue body. + - Always add `--label` flags explicitly — `gh issue create` does not auto-apply labels from templates. +5. Fill in all template fields with concrete information. + +### Error Report + +Fill in both required fields: + +- **What is the URL/path of the document related to this issue?** — provide the published doc URL or the repository file path. Do not leave this blank. +- **How would you like to improve it?** — describe the specific error and the expected correction. Include the current incorrect text and the proposed fix when possible. + +### Change Request + +Fill in all three sections: + +- **Describe what you find is inappropriate or missing in the existing docs.** — be specific about which document, section, or topic is affected. +- **Describe your suggestion or addition.** — explain what should be changed or added and why it helps users. +- **Provide some reference materials (such as documents and websites) if you could.** — link to product PRs, release notes, related docs, or external references that support the request. Write "N/A" if no references are available; do not delete the section. + +### Question + +Before filing: + +- Search existing Stack Overflow questions, Google results, and open/closed GitHub issues as the template instructs. +- Read the relevant docs in `pingcap/docs` and `pingcap/docs-cn`. + +Then describe the question clearly, including what you searched and why the existing documentation did not answer it. + +## Editing Existing Issues + +1. Fetch the current title, body, and labels first. +2. Patch only the intended sections and preserve untouched sections, metadata, and still-valid context. +3. Do not rewrite the issue body from scratch. +4. Preserve the template structure: keep the headings and numbered prompts intact. + +## Preserving Template Structure + +- Keep the hidden HTML comment block (scope reminder and community links) unchanged. +- Keep the template heading (`## Error Report`, `## Change Request`, or `## Question`) unchanged. +- Keep the numbered prompts or instruction text in each template unchanged. +- Do not merge, reorder, or rename template sections. + +## Labels + +- Apply labels explicitly when creating or editing issues. +- For issues created with `gh issue create`, add labels via `-l` flag since the CLI does not auto-apply template labels. +- For existing issues, use `gh issue edit` to update labels. +- Label taxonomy in this repository: + - **Type labels**: `type/bug`, `type/enhancement`, `type/feature-request`, `type/question`, `type/refactor`. Pick the one that matches the issue intent. + - **Area labels**: `area/*` labels identify the documentation area (e.g. `area/tidb-cloud`, `area/planner`, `area/br`, `area/ticdc`, `area/dm`, `area/tidb-lightning`, `area/deploy-upgrade-maintain`, `area/security`, `area/general`). Add at least one when the issue clearly targets a specific area. + - **Priority labels**: `priority/P1`, `priority/P2`. Use when the issue affects published documentation accuracy or user-facing correctness. + - **Workflow labels**: `good first issue`, `help wanted` for community contribution signaling. +- If label permissions are missing, add a comment with `Suggested labels: ...` so maintainers can apply them. + +## File-based Editing + +- Materialize the intended issue body in a local Markdown file. +- For new issues, review that file against the matching issue template before calling `gh`. +- For existing issues, diff the patched body against the current issue body before calling `gh`. + +## Quick Checks + +- The issue title and body are in English. +- The issue uses one of the three available templates (Error Report, Change Request, or Question) — blank issues are not allowed. +- The issue stays within the docs-only scope and does not mix in product bugs or feature requests. +- All template fields are filled in with concrete information, not generic placeholders. +- The template headings, numbered prompts, and HTML comments are preserved. +- Existing issue edits preserve untouched sections and metadata outside the intended patch. +- The issue carries appropriate labels, or a `Suggested labels: ...` comment is present when label permissions are missing. diff --git a/.ai/skills/docs-pr-metadata-guard/SKILL.md b/.ai/skills/docs-pr-metadata-guard/SKILL.md new file mode 100644 index 0000000000000..3db6b727a3863 --- /dev/null +++ b/.ai/skills/docs-pr-metadata-guard/SKILL.md @@ -0,0 +1,85 @@ +--- +name: docs-pr-metadata-guard +description: Use when creating or editing pull requests in pingcap/docs so the PR template sections, version checkboxes, related-link fields, HTML comments, and description structure stay intact. Trigger on tasks involving PR creation, PR body updates, version selection, cherry-pick label decisions, or translating a PR from docs-cn. +--- + +# Docs PR Metadata Guard + +## Overview + +Use this skill for `pingcap/docs` GitHub pull request metadata work. +The goal is to preserve the repository-required PR structure while editing only the mutable fields. + +Before changing a PR body, read `.github/pull_request_template.md`. + +## Workflow + +1. Write PR titles and descriptions in English. +2. For a new PR, start from `.github/pull_request_template.md` instead of writing the body from scratch. + - Copy the template into a local Markdown file and fill in the mutable fields. + - Submit with `gh pr create --body-file `, or use `gh pr create -T .github/pull_request_template.md` to let `gh` load the template as the starting body text (the `-T` / `--template` flag for `gh pr create` takes a file path). + - Review the local file against the template before calling `gh`. +3. Fill in the required sections with concrete information. + - **What is changed, added or deleted? (Required)** — describe what changed and why in clear, specific language. Do not leave this blank or fill it with a generic placeholder. + - **Which TiDB version(s) do your changes apply to? (Required)** — check at least one version checkbox. Follow the affected-version rules in `.ai/shared/repo-conventions.md`: + - Default to `master` only for general improvements, wording fixes, missing-content additions, and corrections not tied to a specific released behavior. + - Check the affected release branch(es) together with `master` when the change involves version-specific behavior, compatibility changes, changed defaults, or fixes in published docs. + - **What is the related PR or file link(s)?** — fill in the translation source link under `This PR is translated from:` when the PR is a translation from `docs-cn`. Fill in other reference links such as product PRs, issues, or related doc PRs under `Other reference link(s):`. + - **Do your changes match any of the following descriptions?** — check all that apply. If the change needs different wording on another branch, check `Need modification after applied to another branch` and comment `/label version-specific-changes-required`. +4. Choose the correct base branch. + - Default to `master` for most documentation PRs. + - Use `release-8.5` for TiDB Cloud documentation changes (see `.ai/shared/repo-conventions.md` for TiDB Cloud conventions). + - Use a specific `release-X.Y` branch when the change is scoped to a single published version and does not apply to `master`. +5. For an existing PR, update only the mutable sections. + - Safe targets: the description text under "What is changed, added or deleted?", the version checkboxes, the related-link fields, and the description checkboxes. + - Do not rename headings, reorder sections, or rewrite the template wholesale. +6. Preserve hidden HTML comments exactly. + - Keep `` unchanged. + - Keep the doc-template reference comment block (``) unchanged. + - Keep `` unchanged. + - Keep `` unchanged. + - Keep `` unchanged. + - Keep `` unchanged. + - Do not delete or rewrite any template comment that explains contributor behavior or bot behavior. +7. Preserve the "Tips for choosing the affected version(s)" guidance block. + - The bold tips paragraph and the `CONTRIBUTING.md` link between the version heading and the checkboxes are part of the template structure. Do not delete, rewrite, or move them. +8. Handle the first-time contributors' checklist correctly. + - If the contributor is not a first-time contributor, remove the entire "First-time contributors' checklist" section as the template instructs. + - If the contributor is a first-time contributor, keep the section and check the CLA checkbox after signing. +9. Prefer file-based edits for GitHub metadata. + - Materialize the intended PR body into a local Markdown file. + - Review that file against the PR template before calling `gh`. +10. After any PR body update, re-read the PR to verify the structure is intact. + +## Version Checkbox Rules + +The version checkboxes in the PR template follow a specific order from newest to oldest. When filling them in: + +- Do not add or remove version lines. The template defines the canonical list. +- Do not reorder the version lines. +- Check only the versions where the change should apply. +- If a version is not in the template list, do not invent a new checkbox line. + +## Cherry-pick and Label Conventions + +- When a change applies to multiple versions, prefer a single PR on the latest applicable branch and use cherry-pick labels for remaining maintained versions. +- Cherry-pick labels follow the pattern `needs-cherry-pick-release-X.Y` (e.g. `needs-cherry-pick-release-8.5`, `needs-cherry-pick-release-7.5`). There is also `needs-cherry-pick-master` for cherry-picks to master. +- If branch-specific wording differences are expected, check `Need modification after applied to another branch` and add the `requires-version-specific-changes` label so cherry-pick reviewers know follow-up edits are required. +- Use the repository's cherry-pick label workflow; do not invent a custom multi-branch process. +- Common non-cherry-pick labels for PRs: + - `type/bugfix`, `type/enhancement`, `type/refactor`, `type/compatibility-or-feature-change` for change type. + - `area/*` labels (e.g. `area/tidb-cloud`, `area/planner`, `area/br`) for the documentation area. + - `translation/from-docs-cn` when the PR is translated from a `docs-cn` PR. + - `translation/welcome` to invite community translation; `translation/no-need` when translation is not needed. + +## Quick Checks + +- The PR body contains the "What is changed, added or deleted? (Required)" heading with a non-empty description below it. +- At least one version checkbox is checked under "Which TiDB version(s) do your changes apply to? (Required)". +- The version checkbox section preserves the template's canonical version list and order. +- The "Tips for choosing the affected version(s)" paragraph and the `CONTRIBUTING.md` link are present between the version heading and the checkboxes. +- All hidden HTML comments from the original template are still present and unmodified (there are six distinct comment blocks — verify none are missing). +- The related-link fields (`This PR is translated from:` and `Other reference link(s):`) are present, even if left at their default values. +- The "Do your changes match any of the following descriptions?" section is present with its checkboxes intact. +- The first-time contributors' checklist is either correctly filled in or removed entirely as instructed. +- The base branch matches the change scope: `master` by default, `release-8.5` for TiDB Cloud, or a specific `release-X.Y` for version-scoped fixes. diff --git a/AGENTS.md b/AGENTS.md index 367525a713a95..1f4b1099d3108 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,8 @@ Use the workflow-specific skills in `.ai/skills/` when they match the task: - `review-doc-pr`: review Markdown diffs, doc PRs, wording, structure, factual accuracy, and possible cross-file impact - `create-or-update-zh-translation-pr`: create or update an EN -> ZH translation PR that maps an English docs change or incremental source update to `pingcap/docs-cn`, using the bundled scripts in `.ai/skills/create-or-update-zh-translation-pr/scripts/` when applicable +- `docs-pr-metadata-guard`: guard PR template structure when creating or editing pull requests — version checkboxes, required sections, HTML comments, related-link fields, and cherry-pick conventions +- `docs-issue-metadata-guard`: guard issue template structure when creating or editing issues — template selection, required fields, scope boundaries, and label hygiene If no existing skill matches the task, follow this file plus the shared guidance and keep the change narrowly scoped. From 78e12155bc3b497128b8a16fc48ee6b6efebfe88 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 12 Jun 2026 09:11:06 +0800 Subject: [PATCH 2/4] format updates --- .ai/skills/docs-issue-metadata-guard/SKILL.md | 13 ++++------ .ai/skills/docs-pr-metadata-guard/SKILL.md | 26 +++++++------------ 2 files changed, 15 insertions(+), 24 deletions(-) diff --git a/.ai/skills/docs-issue-metadata-guard/SKILL.md b/.ai/skills/docs-issue-metadata-guard/SKILL.md index dceed5ff6c5e5..cce9ebd69b4e0 100644 --- a/.ai/skills/docs-issue-metadata-guard/SKILL.md +++ b/.ai/skills/docs-issue-metadata-guard/SKILL.md @@ -5,10 +5,7 @@ description: Use when creating or editing GitHub issues in pingcap/docs so issue # Docs Issue Metadata Guard -## Overview - -Use this skill for `pingcap/docs` GitHub issue metadata work. -The goal is to preserve issue-template structure, scope discipline, and searchable issue descriptions. +Use this skill for `pingcap/docs` GitHub issue metadata work. The goal is to preserve issue-template structure, scope discipline, and searchable issue descriptions. Before creating or editing an issue, read the matching file under `.github/ISSUE_TEMPLATE/`. @@ -94,10 +91,10 @@ Then describe the question clearly, including what you searched and why the exis - For issues created with `gh issue create`, add labels via `-l` flag since the CLI does not auto-apply template labels. - For existing issues, use `gh issue edit` to update labels. - Label taxonomy in this repository: - - **Type labels**: `type/bug`, `type/enhancement`, `type/feature-request`, `type/question`, `type/refactor`. Pick the one that matches the issue intent. - - **Area labels**: `area/*` labels identify the documentation area (e.g. `area/tidb-cloud`, `area/planner`, `area/br`, `area/ticdc`, `area/dm`, `area/tidb-lightning`, `area/deploy-upgrade-maintain`, `area/security`, `area/general`). Add at least one when the issue clearly targets a specific area. - - **Priority labels**: `priority/P1`, `priority/P2`. Use when the issue affects published documentation accuracy or user-facing correctness. - - **Workflow labels**: `good first issue`, `help wanted` for community contribution signaling. + - **Type labels**: `type/bug`, `type/enhancement`, `type/feature-request`, `type/question`, `type/refactor`. Pick the one that matches the issue intent. + - **Area labels**: `area/*` labels identify the documentation area (e.g. `area/tidb-cloud`, `area/planner`, `area/br`, `area/ticdc`, `area/dm`, `area/tidb-lightning`, `area/deploy-upgrade-maintain`, `area/security`, `area/general`). Add at least one when the issue clearly targets a specific area. + - **Priority labels**: `priority/P1`, `priority/P2`. Use when the issue affects published documentation accuracy or user-facing correctness. + - **Workflow labels**: `good first issue`, `help wanted` for community contribution signaling. - If label permissions are missing, add a comment with `Suggested labels: ...` so maintainers can apply them. ## File-based Editing diff --git a/.ai/skills/docs-pr-metadata-guard/SKILL.md b/.ai/skills/docs-pr-metadata-guard/SKILL.md index 3db6b727a3863..35f06c853e760 100644 --- a/.ai/skills/docs-pr-metadata-guard/SKILL.md +++ b/.ai/skills/docs-pr-metadata-guard/SKILL.md @@ -5,10 +5,7 @@ description: Use when creating or editing pull requests in pingcap/docs so the P # Docs PR Metadata Guard -## Overview - -Use this skill for `pingcap/docs` GitHub pull request metadata work. -The goal is to preserve the repository-required PR structure while editing only the mutable fields. +Use this skill for `pingcap/docs` GitHub pull request metadata work. The goal is to preserve the repository-required PR description structure while editing only the mutable fields. Before changing a PR body, read `.github/pull_request_template.md`. @@ -20,12 +17,12 @@ Before changing a PR body, read `.github/pull_request_template.md`. - Submit with `gh pr create --body-file `, or use `gh pr create -T .github/pull_request_template.md` to let `gh` load the template as the starting body text (the `-T` / `--template` flag for `gh pr create` takes a file path). - Review the local file against the template before calling `gh`. 3. Fill in the required sections with concrete information. - - **What is changed, added or deleted? (Required)** — describe what changed and why in clear, specific language. Do not leave this blank or fill it with a generic placeholder. - - **Which TiDB version(s) do your changes apply to? (Required)** — check at least one version checkbox. Follow the affected-version rules in `.ai/shared/repo-conventions.md`: + - **What is changed, added or deleted? (Required)**: describe what changed and why in clear, specific language. Do not leave this blank or fill it with a generic placeholder. + - **Which TiDB version(s) do your changes apply to? (Required)**: check at least one version checkbox. Follow the affected-version rules in `.ai/shared/repo-conventions.md`: - Default to `master` only for general improvements, wording fixes, missing-content additions, and corrections not tied to a specific released behavior. - Check the affected release branch(es) together with `master` when the change involves version-specific behavior, compatibility changes, changed defaults, or fixes in published docs. - - **What is the related PR or file link(s)?** — fill in the translation source link under `This PR is translated from:` when the PR is a translation from `docs-cn`. Fill in other reference links such as product PRs, issues, or related doc PRs under `Other reference link(s):`. - - **Do your changes match any of the following descriptions?** — check all that apply. If the change needs different wording on another branch, check `Need modification after applied to another branch` and comment `/label version-specific-changes-required`. + - **What is the related PR or file link(s)?**: fill in the translation source link under `This PR is translated from:` when the PR is a translation from `docs-cn`. Fill in other reference links such as product PRs, issues, or related doc PRs under `Other reference link(s):`. + - **Do your changes match any of the following descriptions?**: check all that apply. If the change needs different wording on another branch, check `Need modification after applied to another branch` and comment `/label version-specific-changes-required`. 4. Choose the correct base branch. - Default to `master` for most documentation PRs. - Use `release-8.5` for TiDB Cloud documentation changes (see `.ai/shared/repo-conventions.md` for TiDB Cloud conventions). @@ -34,8 +31,6 @@ Before changing a PR body, read `.github/pull_request_template.md`. - Safe targets: the description text under "What is changed, added or deleted?", the version checkboxes, the related-link fields, and the description checkboxes. - Do not rename headings, reorder sections, or rewrite the template wholesale. 6. Preserve hidden HTML comments exactly. - - Keep `` unchanged. - - Keep the doc-template reference comment block (``) unchanged. - Keep `` unchanged. - Keep `` unchanged. - Keep `` unchanged. @@ -65,12 +60,12 @@ The version checkboxes in the PR template follow a specific order from newest to - When a change applies to multiple versions, prefer a single PR on the latest applicable branch and use cherry-pick labels for remaining maintained versions. - Cherry-pick labels follow the pattern `needs-cherry-pick-release-X.Y` (e.g. `needs-cherry-pick-release-8.5`, `needs-cherry-pick-release-7.5`). There is also `needs-cherry-pick-master` for cherry-picks to master. - If branch-specific wording differences are expected, check `Need modification after applied to another branch` and add the `requires-version-specific-changes` label so cherry-pick reviewers know follow-up edits are required. -- Use the repository's cherry-pick label workflow; do not invent a custom multi-branch process. +- Use the repository's cherry-pick label workflow. Do not invent a custom multi-branch process. - Common non-cherry-pick labels for PRs: - - `type/bugfix`, `type/enhancement`, `type/refactor`, `type/compatibility-or-feature-change` for change type. - - `area/*` labels (e.g. `area/tidb-cloud`, `area/planner`, `area/br`) for the documentation area. - - `translation/from-docs-cn` when the PR is translated from a `docs-cn` PR. - - `translation/welcome` to invite community translation; `translation/no-need` when translation is not needed. + - `type/bugfix`, `type/enhancement`, `type/refactor`, `type/compatibility-or-feature-change` for change type. + - `area/*` labels (e.g. `area/tidb-cloud`, `area/planner`, `area/br`) for the documentation area. + - `translation/from-docs-cn` when the PR is translated from a `docs-cn` PR. + - `translation/welcome` to invite community translation; `translation/no-need` when translation is not needed. ## Quick Checks @@ -78,7 +73,6 @@ The version checkboxes in the PR template follow a specific order from newest to - At least one version checkbox is checked under "Which TiDB version(s) do your changes apply to? (Required)". - The version checkbox section preserves the template's canonical version list and order. - The "Tips for choosing the affected version(s)" paragraph and the `CONTRIBUTING.md` link are present between the version heading and the checkboxes. -- All hidden HTML comments from the original template are still present and unmodified (there are six distinct comment blocks — verify none are missing). - The related-link fields (`This PR is translated from:` and `Other reference link(s):`) are present, even if left at their default values. - The "Do your changes match any of the following descriptions?" section is present with its checkboxes intact. - The first-time contributors' checklist is either correctly filled in or removed entirely as instructed. From 551a31b43311cec007d0559e7a79191749cfbe9f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 12 Jun 2026 10:16:50 +0800 Subject: [PATCH 3/4] Apply suggestions from code review --- .ai/AI-README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.ai/AI-README.md b/.ai/AI-README.md index 94336b68c91f0..09a8ee327fac0 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -25,8 +25,8 @@ Use `resources/terms.md` when terminology is uncertain or not covered by the qui - `.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/docs-pr-metadata-guard/`: guard PR template structure when creating or editing pull requests — 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 — template selection, required fields, scope boundaries, and label hygiene +- `.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 The related resources skill includes bundled scripts under `.ai/skills/add-related-resources/scripts/` for: From a4e24a2d43fbdcfdd25497d1c48ba037fb880b12 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 12 Jun 2026 10:17:59 +0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .ai/skills/docs-issue-metadata-guard/SKILL.md | 16 ++++++++-------- .ai/skills/docs-pr-metadata-guard/SKILL.md | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.ai/skills/docs-issue-metadata-guard/SKILL.md b/.ai/skills/docs-issue-metadata-guard/SKILL.md index cce9ebd69b4e0..ce8eaad46922b 100644 --- a/.ai/skills/docs-issue-metadata-guard/SKILL.md +++ b/.ai/skills/docs-issue-metadata-guard/SKILL.md @@ -11,7 +11,7 @@ Before creating or editing an issue, read the matching file under `.github/ISSUE This repository has three issue templates and disables blank issues (`blank_issues_enabled: false` in `config.yml`). Every new issue must use one of the templates. -## Issue Templates +## Issue templates | Template | File | Use when | |---|---|---| @@ -19,7 +19,7 @@ This repository has three issue templates and disables blank issues (`blank_issu | Change Request | `change-request.md` | Suggesting new content, restructuring, adding missing information, improving existing documentation | | Question | `question.md` | Usage questions about documentation that are not answered in existing docs or discussions | -## Scope Boundary +## Scope boundary All three templates include the same scope reminder: @@ -47,14 +47,14 @@ Enforce this boundary: - Always add `--label` flags explicitly — `gh issue create` does not auto-apply labels from templates. 5. Fill in all template fields with concrete information. -### Error Report +### Error report Fill in both required fields: - **What is the URL/path of the document related to this issue?** — provide the published doc URL or the repository file path. Do not leave this blank. - **How would you like to improve it?** — describe the specific error and the expected correction. Include the current incorrect text and the proposed fix when possible. -### Change Request +### Change request Fill in all three sections: @@ -71,14 +71,14 @@ Before filing: Then describe the question clearly, including what you searched and why the existing documentation did not answer it. -## Editing Existing Issues +## Editing existing issues 1. Fetch the current title, body, and labels first. 2. Patch only the intended sections and preserve untouched sections, metadata, and still-valid context. 3. Do not rewrite the issue body from scratch. 4. Preserve the template structure: keep the headings and numbered prompts intact. -## Preserving Template Structure +## Preserving template structure - Keep the hidden HTML comment block (scope reminder and community links) unchanged. - Keep the template heading (`## Error Report`, `## Change Request`, or `## Question`) unchanged. @@ -97,13 +97,13 @@ Then describe the question clearly, including what you searched and why the exis - **Workflow labels**: `good first issue`, `help wanted` for community contribution signaling. - If label permissions are missing, add a comment with `Suggested labels: ...` so maintainers can apply them. -## File-based Editing +## File-based editing - Materialize the intended issue body in a local Markdown file. - For new issues, review that file against the matching issue template before calling `gh`. - For existing issues, diff the patched body against the current issue body before calling `gh`. -## Quick Checks +## Quick checks - The issue title and body are in English. - The issue uses one of the three available templates (Error Report, Change Request, or Question) — blank issues are not allowed. diff --git a/.ai/skills/docs-pr-metadata-guard/SKILL.md b/.ai/skills/docs-pr-metadata-guard/SKILL.md index 35f06c853e760..bd7d0917b4b8f 100644 --- a/.ai/skills/docs-pr-metadata-guard/SKILL.md +++ b/.ai/skills/docs-pr-metadata-guard/SKILL.md @@ -46,7 +46,7 @@ Before changing a PR body, read `.github/pull_request_template.md`. - Review that file against the PR template before calling `gh`. 10. After any PR body update, re-read the PR to verify the structure is intact. -## Version Checkbox Rules +## Version checkbox rules The version checkboxes in the PR template follow a specific order from newest to oldest. When filling them in: @@ -55,7 +55,7 @@ The version checkboxes in the PR template follow a specific order from newest to - Check only the versions where the change should apply. - If a version is not in the template list, do not invent a new checkbox line. -## Cherry-pick and Label Conventions +## Cherry-pick and label conventions - When a change applies to multiple versions, prefer a single PR on the latest applicable branch and use cherry-pick labels for remaining maintained versions. - Cherry-pick labels follow the pattern `needs-cherry-pick-release-X.Y` (e.g. `needs-cherry-pick-release-8.5`, `needs-cherry-pick-release-7.5`). There is also `needs-cherry-pick-master` for cherry-picks to master. @@ -67,7 +67,7 @@ The version checkboxes in the PR template follow a specific order from newest to - `translation/from-docs-cn` when the PR is translated from a `docs-cn` PR. - `translation/welcome` to invite community translation; `translation/no-need` when translation is not needed. -## Quick Checks +## Quick checks - The PR body contains the "What is changed, added or deleted? (Required)" heading with a non-empty description below it. - At least one version checkbox is checked under "Which TiDB version(s) do your changes apply to? (Required)".