diff --git a/.ai/AI-README.md b/.ai/AI-README.md index a7ce766951279..338d2fcf23e1b 100644 --- a/.ai/AI-README.md +++ b/.ai/AI-README.md @@ -24,6 +24,8 @@ 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-update-tidb-docs/`: write new TiDB documentation or update existing documentation based on code PRs, issues, design docs, product specs, or feature descriptions; includes separate reference files for creating new docs (`ref-create-new-doc.md`) and updating existing docs (`ref-update-existing-doc.md`) - `.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-update-tidb-docs/SKILL.md b/.ai/skills/write-update-tidb-docs/SKILL.md new file mode 100644 index 0000000000000..00f464555ac15 --- /dev/null +++ b/.ai/skills/write-update-tidb-docs/SKILL.md @@ -0,0 +1,200 @@ +--- +name: write-update-tidb-docs +description: Write new TiDB documentation or update existing TiDB documentation from code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions. Use when PM or R&D engineers need user-facing docs in pingcap/docs based on code PRs from pingcap/tidb or other TiDB ecosystem repositories, GitHub issues, product specifications, or external reference materials. +--- + +# Write or Update TiDB Docs + +Act as a senior technical writer who has profound knowledge of TiDB. Your task is to write or update user-facing TiDB documentation in `pingcap/docs` based on code changes, PRs, issues, design docs, product specs, rough drafts, existing docs, or short feature descriptions. + +## Quick start + +This is an overview of the full workflow below — the create-vs-update decision is made in Step 4, not before. + +1. Load shared context (Step 1). +2. Analyze the input and determine the target branch (Steps 2–3). +3. Decide create vs. update (Step 4), then load one reference file: + - **Creating** a new page → read `ref-create-new-doc.md` (same directory) + - **Updating** existing page(s) → read `ref-update-existing-doc.md` (same directory) +4. Follow that reference file's workflow end-to-end. + +## Ground every fact in the source + +Documentation generated from code fails most often by being well-formatted but factually wrong. Before writing any specific value, follow these rules: + +- Every concrete fact — default value, range, type, scope, version number, behavior, error message, syntax — must be traceable to an authoritative source: the PR diff, the code, tests, or an existing doc. +- Never infer or invent a value because it "looks reasonable." A plausible-but-wrong default is worse than an acknowledged gap. +- If a fact cannot be derived from the available sources, insert a clearly marked placeholder (for example, ``) and list it under **Open questions** in the plan, rather than guessing. +- When the source and an existing doc disagree, note the conflict under **Open questions** in the plan instead of silently picking one. + +## Accepted inputs + +| Input type | Examples | +| --- | --- | +| Code PR | `pingcap/tidb` PR link, diff, or reference | +| GitHub issue | Feature request, bug report, design discussion | +| Product spec | Feature specification, product requirement document | +| Design doc | Technical design, RFC, architecture proposal | +| External reference | Blog post, conference talk notes, user feedback | +| Rough notes | Bullets, chat messages, informal descriptions | +| Existing docs | Current doc page that needs improvement | + +Multiple inputs can be combined. More context = fewer questions needed. + +## Defaults + +- Inspect first, confirm when uncertain, then edit. +- Prefer updating existing docs over creating new pages. +- Not every code change needs a doc update. Documentation must justify its + maintenance cost. +- English in `pingcap/docs` is the primary output. For Chinese docs, finish + English first, then use the `create-or-update-zh-translation-pr` skill. +- If the user asks about local changes without naming files, start with + `git status -u` or `git show --name-status`. + +## Step 1: Load shared context + +Always read before making any doc changes: + +- `.ai/shared/repo-conventions.md` +- `.ai/shared/writing-style.md` + +Read only when relevant: + +- `.ai/shared/translation-rules.md` — when translation is involved +- `resources/terms.md` — when terminology is uncertain + +## Step 2: Analyze the input + +### From a code PR + +```bash +gh pr view --json title,body,labels,baseRefName,headRefName,files +gh pr diff +``` + +Scan for documentation-relevant patterns. This table is for **triage** — deciding whether docs are affected and which area. For the exact target-file mapping with specific file paths, see `ref-update-existing-doc.md`. + +| Code pattern | Likely doc area | +| --- | --- | +| New/changed `SysVar` / `DefValue` | System variables | +| New/changed config field / `toml` tag | Configuration files | +| New/changed command-line flag | Command-line flags | +| New SQL statement or grammar change | SQL statements | +| New built-in function | Functions and operators | +| New `INFORMATION_SCHEMA` table | Information schema | +| New feature flag or experimental gate | Feature doc (new or existing) | +| Changed default or compatibility | Relevant docs + possibly release notes | + +Focus on user-facing changes. Skip internal refactors that do not affect behavior. + +### From a product spec, issue, or design doc + +Extract: + +1. What can users now do, configure, or observe that they could not before? +2. Which components are affected? +3. Which versions will include this? +4. Any constraints, limitations, or compatibility concerns? + +### From rough notes or verbal description + +Extract key user-facing facts. Ask focused questions only for facts that cannot +be derived from code, tests, or existing docs. + +## Step 3: Determine the target branch and version + +### Target branch + +| Source context | Docs target branch | +| --- | --- | +| New development (default) | `master` only | +| Version-specific behavior across maintained versions | `master` + `needs-cherry-pick-release-X.Y` labels | +| `/tidb-cloud/` content | `release-8.5` | +| `/ai/` content | `release-8.5` | + +Follow the repository's cherry-pick model (see `.ai/shared/repo-conventions.md`): default to a single PR on the latest applicable branch (usually `master`) and rely on cherry-pick labels for other maintained versions, rather than opening parallel PRs per branch. When in doubt, target `master`. + +### Version number for "Starting from vX.Y" notes + +Many entries need a precise version (for example, "This variable was introduced in vX.Y"). Determine it from the source — do not guess: + +- Code PR: derive from the PR milestone, the target release branch, or the next unreleased version on `master`. +- Spec/issue/design doc: use the stated target version. + +If the version cannot be determined from the source, mark it with a placeholder and list it under **Open questions** instead of inventing a number. + +## Step 4: Decide — create new page or update existing + +Ask these questions: + +1. Does this change have a natural home in an existing page? +2. Would adding it to an existing page make that page too long or dilute its + focus? +3. Does it introduce a distinct user task or feature that needs standalone + discoverability? +4. Is there enough substance for a standalone page (≥3 meaningful sections)? + +| Answer | Action | +| --- | --- | +| Fits in existing page(s) | → Load `ref-update-existing-doc.md` and refer to it to update the existing page(s) | +| Needs a new standalone page | → Load `ref-create-new-doc.md` and refer to it to create a new standalone page | +| New page + related updates to existing pages | → Load both; start with `ref-create-new-doc.md` | + +Then follow the loaded reference file's workflow from start to finish. + +## Shared gotchas + +These apply to both creating and updating: + +- The `/tidb-cloud/` and `/ai/` folders live only in `release-8.5`. Update English documentation only (which means content only in the pingcap/docs repository); Chinese documentation is AI-translated weekly. +- Do not change `CustomContent` blocks without understanding platform-specific rendering. +- Do not silently broaden scope from a targeted fix into cross-file rewrites. +- Preserve code samples, commands, SQL, config names, API fields, JSON, EBNF, + and UI strings unless the task requires changing them or they are clearly wrong. + +## Where this skill stops + +This skill produces **local edits + validation + a completion report**. It does not create branches, commit, push, or open a PR on its own. + +- After editing and validating, report the changed files and follow-ups, then stop. +- Create a branch, commit, or open a PR only when the user explicitly asks, or hand off to the workflow the user prefers. +- Chinese translation, release notes, and PR creation are separate steps — flag them as follow-ups (see **Coordinating with other skills**) rather than doing them inline. + +## Coordinating with other skills + +| Task | Skill | +| --- | --- | +| Translate English documentation to Chinese | `create-or-update-zh-translation-pr` | +| Review and update release notes | `write-review-translate-release-notes` | +| Review and update documentation PR | `review-doc-pr` | +| Update `summary` front matter | `writing-doc-summaries` | + +## Output format + +**Plan (before editing):** + +``` +Target: +Source: +Action: +Doc type: +Outline: +Related updates: +Open questions: +``` + +**Completion report:** + +``` +Changed files: +- : + +Source: + +Validation: +- : + +Follow-up: +- +``` diff --git a/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md new file mode 100644 index 0000000000000..bfe55e993fabf --- /dev/null +++ b/.ai/skills/write-update-tidb-docs/ref-create-new-doc.md @@ -0,0 +1,268 @@ +# Create New TiDB Documentation + +Self-contained workflow for creating a new documentation page in `pingcap/docs`. +Follow these steps sequentially after SKILL.md has determined that a new page is +needed. + +## Confirm the decision to create + +This is a final sanity re-check of the create-vs-update decision already made in `SKILL.md` Step 4 (the authoritative decision point) — not a second, independent decision. If any criterion below fails, switch to `ref-update-existing-doc.md`. + +A new page is justified when all of these are true: + +- The content does not fit cleanly as a section of an existing page. +- There is enough substance for ≥3 meaningful sections. +- The content has standalone discoverability value (users might search for it + directly). + +Typical triggers: new feature with its own scenarios/config/limitations, new SQL +statement, new `INFORMATION_SCHEMA` table, new integration/tool, new +troubleshooting workflow. + +Do **not** create a new page if: + +- The content can be a section in an existing page without making it too long. +- The content would be too thin (fewer than ~3 sections). +- Similar content already exists and could be expanded instead. + +## 1. Choose doc type and template + +| Doc type | User question it answers | Template to read | +| --- | --- | --- | +| New feature | "What is this? Why use it? How?" | `resources/doc-templates/template-new-feature.md` | +| Task | "How do I do X step by step?" | `resources/doc-templates/template-task.md` | +| Concept | "What is X and how does it work?" | `resources/doc-templates/template-concept.md` | +| Reference | "What are the params/syntax/options?" | `resources/doc-templates/template-reference.md` | +| Troubleshooting | "Something is wrong, how to fix?" | `resources/doc-templates/template-troubleshooting.md` | + +Read the selected template before drafting. Use it as a structural skeleton; skip +sections that do not apply. + +For features combining concept + usage + reference (common in TiDB), use the +**new feature** template. Split into multiple pages only when content naturally +exceeds ~1500 words per concern. + +## 2. Choose file path and name + +Look at where similar docs live: + +```bash +# Find peers in the TOC +rg -n "|" TOC*.md + +# Check existing directory structure +ls / +``` + +**Naming rules:** + +- Lowercase, hyphen-separated: `feature-name.md` +- Concise and stable — avoid version numbers or overly specific wording +- Follow existing patterns in the same area + +**Placement rules:** + +| Feature scope | Path | +| --- | --- | +| Component-specific (TiCDC, TiFlash, TiProxy, DM, BR) | `/feature-name.md` | +| SQL statement | `sql-statements/sql-statement-.md` | +| INFORMATION_SCHEMA table | `information-schema/information-schema-.md` | +| Function/operator | `functions-and-operators/.md` | +| Cross-component or general | Root: `feature-name.md` | + +## 3. Determine TOC placement + +Every navigable page needs a TOC entry. + +### Which TOC file? + +| Content area | TOC file | +| --- | --- | +| TiDB Self-Managed (most common) | `TOC.md` | +| AI / vector search / pytidb / MCP | `TOC-ai.md` | +| App development guides | `TOC-develop.md` | +| Best practices | `TOC-best-practices.md` | +| API docs | `TOC-api.md` | +| TiDB release notes | `TOC-tidb-releases.md` | +| TiDB Cloud general | `TOC-tidb-cloud.md` | +| TiDB Cloud tier-specific | `TOC-tidb-cloud-starter.md` / `essential` / `premium` | +| TiDB Cloud release notes | `TOC-tidb-cloud-releases.md` | + +### Where in the TOC? + +1. Find the relevant section: `rg -n "" TOC.md` +2. Look at neighbors — TOC groups by component, then by complexity (overview → + getting started → usage → reference → troubleshooting). +3. Place the entry adjacent to similar items at the correct nesting level. + +**Format** (2-space indent per level): + +```markdown +- Category Name + - [Page Title](/path/to/file.md) + - [New Page Title](/path/to/new-file.md) + - [Sub Page](/path/to/sub.md) +``` + +**TOC title**: title case, concise (3–7 words), match the doc H1 when feasible. + +## 4. Write front matter + +```yaml +--- +title: +summary: +--- +``` + +- `title` must match the H1 exactly, in title case, and stay within ~59 characters. +- `summary` must not start with `>`, `*`, `#`, `-`, or `[`. +- `summary` tells readers what they will learn or accomplish. +- For exact `summary` length rules and verb guidance, follow the `writing-doc-summaries` skill (target 115–145 characters, 45-character absolute minimum). +- SQL statement reference pages use a fixed template defined in the `writing-doc-summaries` skill that falls below 115 characters — that is expected. +- Add `aliases` only if replacing an older page URL. + +## 5. Draft the document + +### Writing principles + +- Start with what users care about — not internal background. +- Put conditions before instructions. +- Define jargon on first use. +- Include realistic, runnable examples. +- End with related resources or next steps. + +### Structure by doc type + +**New feature:** + +``` +# Feature Name + Intro: what it does, why it matters, when to use it. + +## Use cases + +## Prerequisites (if needed) + +## How to use +### Method 1: (recommended) +### Method 2: + +## Parameter reference (if applicable) + +## Limitations + +## Compatibility + +## FAQ (if needed) + +## See also +``` + +**Task:** + +``` +# Task Title + Intro: what this helps you accomplish. + +## Prerequisites + +## Step 1. + +## Step 2. + +## Step 3. + +## What's next +``` + +**Concept:** + +``` +# Concept Title + Intro: what this concept is and why it matters. + +## Architecture / How it works + +## Key features + +## Limitations (if applicable) + +## What's next +``` + +**Reference:** + +``` +# Reference Title + Intro: what this reference covers. + +## Category 1 +### Item / parameter + +## Category 2 +### Item / parameter +``` + +**Troubleshooting:** + +``` +# Troubleshoot + Intro: what problems this covers. + +## Common causes +### Cause 1 + Symptom → Solution +### Cause 2 + +## Other causes +### Cause 3 +``` + +### Co-authoring mode (for substantial docs) + +When the doc is expected to exceed ~800 words or has unclear scope: + +1. Propose 3–5 core sections. Get confirmation. +2. Start with the highest-value or most-uncertain section. +3. Draft section by section. Ask questions only when facts cannot be derived + from available sources. +4. After drafting, run a reader test: predict 5–10 questions a real user would + ask. Verify the doc answers them. +5. Ask: can anything be removed without losing value? + +## 6. Handle associated updates + +| Check | Action when needed | +| --- | --- | +| TOC entry | Always required | +| Overview page | Add brief mention or link (e.g., `sql-statement-overview.md`) | +| Related docs | Add "See also" links where users benefit | +| Release notes | Flag for the release notes skill | +| System variable page | Cross-link if the feature has variables | +| Compatibility page | Update if MySQL compat is affected | + +## 7. Validate + +```bash +./scripts/markdownlint +./scripts/verify-links.sh # if links were added +``` + +Also check: + +- [ ] Front matter: title matches H1; summary follows `writing-doc-summaries` length rules (115–145 chars target, ≥45 chars) +- [ ] TOC: correct file, correct level, correct indentation +- [ ] Heading levels: no skipped levels, exactly one H1 +- [ ] File name: lowercase, hyphen-separated, `.md` extension +- [ ] A user finding this via search can complete their task without hidden + context + +## Common mistakes + +- Page too thin — should have been a section in an existing page. +- TOC entry in wrong file or wrong nesting level. +- Intro describes what the doc will do instead of starting with useful info. +- Missing overview/reference page updates that help users discover the new page. +- Forgetting `aliases` when replacing an older page. +- Writing content that duplicates an existing page without adding new user value. diff --git a/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md new file mode 100644 index 0000000000000..396109629b1b6 --- /dev/null +++ b/.ai/skills/write-update-tidb-docs/ref-update-existing-doc.md @@ -0,0 +1,252 @@ +# Update Existing TiDB Documentation + +Self-contained workflow for updating existing documentation pages in +`pingcap/docs`. Follow these steps sequentially after SKILL.md has determined +that existing pages need updating. + +## 1. Identify target docs + +### From code patterns + +This is the authoritative code-pattern → target-file mapping. It expands the triage table in `SKILL.md` with exact file paths. + +| Code pattern | Primary target | +| --- | --- | +| New/changed `SysVar` / `DefValue` | `system-variables.md` | +| New/changed config field / `toml` tag | `tidb-configuration-file.md` / `tikv-configuration-file.md` / `pd-configuration-file.md` / `tiflash/tiflash-configuration.md` | +| New/changed command-line flag | `command-line-flags-for-*-configuration.md` | +| Changed SQL grammar (parser `.y`) | `sql-statements/sql-statement-.md` | +| New/changed function | `functions-and-operators/` | +| New INFORMATION_SCHEMA column | `information-schema/information-schema-.md` | +| Changed metric or alert | `grafana-*.md` or component monitoring docs | +| Changed default/behavior | Feature doc + compatibility notes | +| New error code | Error reference docs | +| Changed API | API reference docs | + +### Search strategies + +```bash +# Find docs mentioning the feature/config/variable +rg -l "" --type md + +# Find where it appears in TOC +rg -n "" TOC*.md + +# Find docs that link to the target page +rg -l "/path-to-target.md" --type md +``` + +Also check component directories (`ticdc/`, `tiflash/`, `tiproxy/`, `dm/`, +`br/`) when the change touches a specific component. + +## 2. Assess related docs (impact radius) + +A single code change often ripples into multiple pages. + +### Direct impact (update in the same edit) + +- The primary reference page (config file, system variables, flags) +- The feature/task page describing how to use the changed behavior +- The SQL statement page if syntax changed + +### Indirect impact (assess case by case) + +| Category | Examples | +| --- | --- | +| Overview pages | `sql-statement-overview.md`, `functions-and-operators-overview.md` | +| Feature lists | `basic-features.md` | +| Compatibility | `mysql-compatibility.md`, feature compat tables | +| Limitations | `tidb-limitations.md`, feature-specific limitations | +| FAQ | Feature FAQ pages | +| Best practices | Operational or schema best practices | +| Troubleshooting | If the change resolves or introduces known issues | +| Release notes | If user-facing in a specific version | + +**Scope rule:** + +- Direct-impact pages → update them. +- Indirect pages where the current text would become **incorrect** → update them. +- Indirect pages where the update is merely **nice to have** → flag in output + notes, do not expand scope without user confirmation. + +## 3. Read the existing page before editing + +Before touching a file, understand: + +| Aspect | What to look for | +| --- | --- | +| Structure | Heading hierarchy, section order, content flow | +| Voice | Terse vs. explanatory, imperative vs. descriptive | +| Pattern | How similar items on this page are documented | +| Terminology | Which terms are used — do not introduce synonyms | +| Scope | What the page covers and explicitly excludes | +| Sort order | Alphabetical, logical grouping, or chronological | + +**Key principle:** the updated section must read as if written by the same author +as the rest of the page. New content should not stand out stylistically. + +## 4. Plan the edit + +For each target page, determine: + +- **Where**: which section, which position within the section. +- **What**: add, change, or remove. +- **How much**: surrounding context to adjust for flow. + +### Placement conventions + +| Page type | Typical order | +| --- | --- | +| System variables | Alphabetical by name | +| Config parameters | Grouped by `[section]`, then by functionality | +| SQL statement page | Synopsis → Description → Examples → See also | +| Function reference | Syntax → Parameters → Return → Examples | +| Feature page | Intro → Usage → Limitations → Compatibility | + +When adding a new item to a list, table, or parameter section: + +- Insert in the correct sort position. +- Match the existing format exactly (fields, punctuation, backticks, spacing). +- Do not reorder existing items unless fixing a clear sorting error. + +## 5. Write — match style and format + +### Match the entry format + +Study 2–3 neighboring entries on the same page and replicate their pattern. + +**System variable entry example:** + +```markdown +### variable_name + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Integer +- Default value: `100` +- Range: `[0, 10000]` +- This variable controls ... +``` + +**Config parameter entry example:** + +```markdown +### `parameter-name` + +- Default value: `value` +- Range: `[min, max]` +- Description explaining what the parameter controls. +``` + +New entries must follow the identical field order, punctuation, and detail level. + +### Match voice and depth + +- If the page uses terse descriptions → keep new content terse. +- If the page writes full paragraphs → write comparably. +- If the page includes examples for each item → add an example. +- If the page omits examples → do not add one only for the new item unless + critical for understanding. + +### Version annotations + +For version-specific changes, use the established format on the page: + +- "Starting from vX.Y, ..." or "This variable was introduced in vX.Y." +- For behavior changes, state both old and new behavior when helpful. +- Ensure version notes are accurate for the target branch. + +### Additions vs. modifications vs. removals + +**Adding** (new param, new section, new example): + +- Follow the format of adjacent entries. +- Maintain heading level hierarchy. +- Add transitional context if needed for flow. + +**Modifying** (changed default, updated behavior): + +- Change only the specific facts that changed. +- Preserve sentence structure and style when possible. +- Add a version note if the change is version-specific. +- If breaking, add a warning. + +**Removing** (deprecated feature, removed limitation): + +- Remove cleanly; check for orphaned references on the same page. +- For deprecated features, add a deprecation note rather than deleting docs for + still-functional features. +- Link to the replacement or migration path. + +## 6. Verify cross-document consistency + +After editing, check: + +- [ ] Same fact appears in multiple docs → all updated? +- [ ] Changed a heading → anchors/links from other docs still valid? +- [ ] Feature gained capabilities → summary/overview pages still accurate? +- [ ] Behavior changed for MySQL compat → `mysql-compatibility.md` updated? +- [ ] Default changed → examples relying on old default still correct? +- [ ] Removed content → no orphaned cross-references remain? + +## 7. Validate + +```bash +./scripts/markdownlint +./scripts/verify-links.sh # if headings/anchors/links changed +``` + +Also: + +- [ ] Re-read the changed section with 2–3 surrounding sections — does it flow + naturally? +- [ ] Facts match the source (code PR, issue, spec)? +- [ ] For procedural content, mentally trace the steps with the new info. +- [ ] No style discontinuity between new and existing content. + +## Common update patterns + +### New system variable + +1. Add entry in `system-variables.md` in alphabetical order, matching format. +2. Add to `system-variable-reference.md` if applicable. +3. Update the feature page to mention the variable. +4. If the variable controls a new feature, the feature doc is primary; the + variable entry should link to it. + +### New config parameter + +1. Add entry in `*-configuration-file.md` under the correct `[section]`. +2. Match the exact format of neighbors. +3. If there is a corresponding CLI flag, update the flag doc too. + +### Changed default value + +1. Change the value in the parameter/variable description. +2. Add version note ("Starting from vX.Y, the default value changes to ..."). +3. Check if examples elsewhere assume the old default. +4. If breaking, add a compatibility/warning note. + +### Removed limitation + +1. Update the feature doc's limitations section. +2. Update `tidb-limitations.md` if listed there. +3. Remove or mark as unnecessary any workaround documentation. + +### Deprecation + +1. Add deprecation notice with version and expected removal timeline. +2. Update "recommended" guidance that points to the deprecated feature. +3. Link to the replacement. +4. Keep documentation for still-functional deprecated features. + +## Common mistakes + +- Updating one occurrence but missing the same fact in other docs. +- Breaking format/style consistency with surrounding entries. +- Expanding scope into unrelated improvements. +- Adding version notes inaccurate for the target branch. +- Leaving orphaned references when removing content. +- Introducing new terminology that conflicts with existing usage on the page. +- Rewriting surrounding text unnecessarily while making a targeted edit. diff --git a/AGENTS.md b/AGENTS.md index 1f4b1099d3108..f4ac5205bd8be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,7 @@ 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 +- `write-update-tidb-docs`: write new TiDB documentation or update existing documentation based on code PRs from `pingcap/tidb` or other TiDB ecosystem repositories, issues, design docs, or feature descriptions - `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