tidb-lightning: recommend matching TiDB Lightning and TiDB versions

[YangKeao]

What is changed, added, or deleted? (Required)

Recommend using the same version of TiDB Lightning as the target TiDB cluster consistently across the deployment guide, FAQ, quick start, and troubleshooting documentation.

• Replace the blanket backward-compatibility claim and latest-version recommendation in the deployment guide with the matching-version recommendation.
• Reframe the FAQ as "Which TiDB Lightning version should I use?" and focus the answer on matching the target TiDB cluster version instead of historical minimum-version information.
• Specify the matching version in TiUP installation and quick-start launch examples, and retain the original task's version in the FAQ restart example.
• Align upgrade advice in both troubleshooting pages with the same recommendation.
• Address review feedback: use the documentation version variable in examples, link the installation step, clarify restart wording, and pin the Lightning version in the additional example-data and migration guides identified in review and their available translations.

This is a documentation guidance correction, not a product behavior change.

Validation: git diff --check and the repository's ./scripts/markdownlint passed for all changed Markdown files. The version-selection FAQ heading was changed; searches in both repositories found no references to its old anchor. The new Step 3 links were checked against the installation headings. No page aliases were changed. TiUP installation and version-pinned execution were also smoke-tested with Lightning v8.5.0; no data import was performed.

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.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

• Related code change PR links (if applicable): N/A (documentation-only correction).
• This PR is translated from: N/A.
• Other reference link(s):
  • Chinese documentation PR: tidb-lightning: recommend matching TiDB Lightning and TiDB versions docs-cn#21945
  • https://docs.pingcap.com/zh/tidb/dev/deploy-tidb-lightning/
  • https://docs.pingcap.com/zh/tidb/dev/tidb-lightning-faq/

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• Documentation
  • Updated TiDB Lightning installation and startup instructions to use a version matching the target TiDB cluster.
  • Updated TiUP and manual deployment guidance to specify the TiDB Lightning version explicitly.
  • Updated import and migration instructions to use the target cluster’s TiDB Lightning version.
  • Updated restart instructions to reuse the originally installed TiDB Lightning version.
  • Clarified upgrade and troubleshooting recommendations to keep TiDB Lightning and the target TiDB cluster on the same version.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingcap/docs/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: d29b0886-0d9a-4f90-9dd8-145708645517

📥 Commits

Reviewing files that changed from the base of the PR and between 9466cd9 and 84ac28e.

📒 Files selected for processing (8)

• get-started-with-tidb-lightning.md
• import-example-data.md
• migrate-from-sql-files-to-tidb.md
• migrate-large-mysql-to-tidb.md
• tidb-lightning/deploy-tidb-lightning.md
• tidb-lightning/tidb-lightning-faq.md
• tidb-lightning/troubleshoot-tidb-lightning.md
• tidb-troubleshooting-map.md

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The documentation now directs users to use a TiDB Lightning version that matches the target TiDB cluster during installation, startup, restart, download, import, and upgrade procedures.

Changes

Version alignment

Layer / File(s)	Summary
Versioned installation and operational guidance get-started-with-tidb-lightning.md, import-example-data.md, migrate-from-sql-files-to-tidb.md, migrate-large-mysql-to-tidb.md, tidb-lightning/deploy-tidb-lightning.md, tidb-lightning/tidb-lightning-faq.md	Installation and startup commands now include a TiDB Lightning version. Deployment, import, migration, and restart guidance now recommends matching the target TiDB cluster version.
Versioned upgrade guidance tidb-lightning/troubleshoot-tidb-lightning.md, tidb-troubleshooting-map.md	Upgrade guidance now recommends keeping TiDB Lightning and the target TiDB cluster at the same version.

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Suggested reviewers: qiancai

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description covers the required change, affected TiDB version, related links, AI involvement, validation, and checklist items. It clearly explains the documentation-only scope.
Title check	✅ Passed	The title clearly and concisely describes the main documentation change: recommending matching TiDB Lightning and TiDB cluster versions.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: pingcap/docs/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e5ce2084-c8b6-4e38-b0d0-f3bc9efcc27f

📥 Commits

Reviewing files that changed from the base of the PR and between f9f08f3 and e8f0a02.

📒 Files selected for processing (5)

• get-started-with-tidb-lightning.md
• tidb-lightning/deploy-tidb-lightning.md
• tidb-lightning/tidb-lightning-faq.md
• tidb-lightning/troubleshoot-tidb-lightning.md
• tidb-troubleshooting-map.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

[ti-chi-bot]

@D3Hunter: adding LGTM is restricted to approvers and reviewers in OWNERS files.

Details

In response to this:

Instructions 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.

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-09-21 01:45:05.713015749 +0000 UTC m=+601551.650673342: ☑️ agreed by qiancai.

[qiancai]

/approve

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: qiancai

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [qiancai]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

In response to a cherrypick label: new pull request created to branch release-8.5: #23917.