Skip to content

tidb-lightning: recommend matching TiDB Lightning and TiDB versions - #21945

Merged
ti-chi-bot[bot] merged 3 commits into
pingcap:masterfrom
YangKeao:docs/lightning-match-tidb-version
Sep 21, 2026
Merged

ti-chi-bot[bot] merged 3 commits into
pingcap:masterfrom
YangKeao:docs/lightning-match-tidb-version

Conversation

@YangKeao

@YangKeao YangKeao commented Sep 20, 2026 •

Copy link
Copy Markdown
Member

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. Update the Chinese FAQ summary accordingly.
  • Specify the matching version in TiUP installation and quick-start launch examples, retain the original task's version in the FAQ restart example, and align the quick-start summary.
  • 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 migration guides identified in review and align them with the English documentation.

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 (in Chinese).

  • 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)?

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

  • 文档
    • 更新 TiDB Lightning 的安装、部署和启动示例,要求使用与目标 TiDB 集群一致的版本。
    • 调整手动安装及版本选择建议,强调 TiDB Lightning 与目标集群版本保持一致。
    • 更新常见问题和故障排查指南,说明升级到较新版本可能改善导入速度,并建议同步匹配目标集群版本。

@ti-chi-bot ti-chi-bot Bot added missing-translation-status This PR does not have translation status info. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Sep 20, 2026
@coderabbitai

coderabbitai Bot commented Sep 20, 2026 •

Copy link
Copy Markdown

Review Change StackReview Change Stack

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
📝 Walkthrough

Walkthrough

文档统一建议使用与目标 TiDB 集群版本匹配的 TiDB Lightning。安装、启动、导入、版本要求和故障排查说明均已更新。

Changes

TiDB Lightning 版本指导

Layer / File(s) Summary
安装、启动和导入命令更新
get-started-with-tidb-lightning.md, tidb-lightning/deploy-tidb-lightning.md, tidb-lightning/tidb-lightning-faq.md, migrate-from-sql-files-to-tidb.md, migrate-large-mysql-to-tidb.md
安装、启动和导入命令改为使用 <version>。文档要求该版本与目标 TiDB 集群版本匹配。
版本要求与排查建议
tidb-lightning/tidb-lightning-faq.md, tidb-lightning/troubleshoot-tidb-lightning.md, tidb-troubleshooting-map.md
版本要求和导入速度排查建议改为推荐使用或升级到与目标 TiDB 集群版本匹配的 TiDB Lightning。

Priority: ⬇️ Low

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.
Title check ✅ Passed 标题准确概括了主要变更,即建议 TiDB Lightning 与目标 TiDB 集群使用相同版本。标题简洁且与变更内容一致。
Description check ✅ Passed 描述完整说明了变更范围、版本适用范围、相关链接、AI 参与情况和验证结果。必需章节已填写,内容与变更目标一致。
✨ 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

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 9dd8680f-6207-4908-9a2c-0a6d529dd8e1

📥 Commits

Reviewing files that changed from the base of the PR and between 5e756fa and 506af29.

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

Comment thread get-started-with-tidb-lightning.md
Comment thread get-started-with-tidb-lightning.md Outdated
Comment thread tidb-lightning/deploy-tidb-lightning.md Outdated
Comment thread get-started-with-tidb-lightning.md Outdated
Comment thread tidb-lightning/tidb-lightning-faq.md Outdated

@qiancai qiancai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rest LGTM

@ti-chi-bot ti-chi-bot Bot added the needs-1-more-lgtm Indicates a PR needs 1 more LGTM. label Sep 20, 2026
@ti-chi-bot

ti-chi-bot Bot commented Sep 20, 2026

Copy link
Copy Markdown

[LGTM Timeline notifier]

Timeline:

  • 2026-09-20 10:14:23.904142986 +0000 UTC m=+545709.841800570: ☑️ agreed by qiancai.

@qiancai qiancai self-assigned this Sep 20, 2026
@qiancai qiancai added the needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. label Sep 20, 2026
@ti-chi-bot ti-chi-bot Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Sep 20, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟠 Major · 将 schema 复制示例改为版本限定命令。 · tidb-lightning-faq.md:222

tidb-lightning/tidb-lightning-faq.md:222
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

将 schema 复制示例改为版本限定命令。

本 PR 已在重启示例中要求保留原任务版本,但该示例仍未指定 TiDB Lightning 版本。用户无法确认该命令使用的版本是否与目标 TiDB 集群匹配。请同步使用版本限定形式。

可直接提交的修改
    tiup tidb-lightning:<version> -config /tmp/tidb-lightning.toml

ℹ️ Review info
⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 7369b00b-65f4-43f4-a7d1-0c52a111abe5

📥 Commits

Reviewing files that changed from the base of the PR and between 6405169 and a2ba304.

📒 Files selected for processing (7)
  • get-started-with-tidb-lightning.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.

@ti-chi-bot

ti-chi-bot Bot commented Sep 21, 2026

Copy link
Copy Markdown

@qiancai: Your lgtm message is repeated, so it is ignored.

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.

@qiancai qiancai added translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. and removed missing-translation-status This PR does not have translation status info. labels Sep 21, 2026
@qiancai

qiancai commented Sep 21, 2026

Copy link
Copy Markdown
Collaborator

/approve

@qiancai qiancai added the lgtm label Sep 21, 2026
@ti-chi-bot

ti-chi-bot Bot commented Sep 21, 2026

Copy link
Copy Markdown

[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:

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 ti-chi-bot Bot added the approved label Sep 21, 2026
@ti-chi-bot
ti-chi-bot Bot merged commit d1ddc4d into pingcap:master Sep 21, 2026
11 checks passed
@ti-chi-bot

Copy link
Copy Markdown
Member

In response to a cherrypick label: new pull request created to branch release-8.5: #21946.
But this PR has conflicts, please resolve them!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved lgtm needs-1-more-lgtm Indicates a PR needs 1 more LGTM. needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants