Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

remove excessive clarifications as they apply to earlier GA releases #4549

Open
morgo opened this issue Dec 30, 2020 · 5 comments
Open

remove excessive clarifications as they apply to earlier GA releases #4549

morgo opened this issue Dec 30, 2020 · 5 comments
Assignees
Labels
lifecycle/frozen Issues with this label will not be labeled as "stale".

Comments

@morgo
Copy link
Contributor

morgo commented Dec 30, 2020

Change Request

This repository is ONLY used to solve issues related to DOCS.
For other issues (related to TiDB, PD, etc), please move to other repositories.

Please answer the following questions before submitting your issue. Thanks!

  1. Describe what you find is inappropriate or missing in the existing docs.

See: https://docs.pingcap.com/tidb/dev/backup-and-restore-tool

  1. Describe your suggestion or addition.

There are a lot of clarifications which are only historically relevant. By keeping them here, they make it harder for first time readers to process the document:

BR only supports TiDB v3.1 and later versions.
For v3.1 clusters, the new collation framework is not supported, so you can see it as disabled.
For example, assume that data is backed up from a v3.1 cluster and will be restored to a v4.0 cluster.
Meanwhile, because TiDB v4.0 uses leader count for load balancing by default, leaders are greatly different in size, resulting in uneven distribution of backup data on each node.
TiDB v4.0.2 and later versions support backup and restore operations using SQL statements.
If the BR version is earlier than v4.0.3, and the backup duration might exceed the tikv_gc_life_time configuration which is 10m0s by default (10m0s means 10 minutes), increase the value of this configuration item.
Since v4.0.3, BR automatically adapts to GC and you do not need to manually adjust the tikv_gc_life_time value.

For the use-case of backup+upgrade (where some of these restrictions apply), the documentation should be on the manual page for upgrading from the previous series (a new document under Maintain -> Upgrade).

  1. Provide some reference materials (documents, websites, etc) if you could.

The MySQL docs use the convention of removing the version-specific language in the GA that follows when it was introduced. See this example:

@TomShawn
Copy link
Contributor

TomShawn commented Jan 5, 2021

@3pointer @overvenus PTAL, thanks

@lilin90
Copy link
Member

lilin90 commented Mar 2, 2021

@qiancai Please also take a look.

@TomShawn TomShawn added the lifecycle/frozen Issues with this label will not be labeled as "stale". label Mar 3, 2021
@qiancai
Copy link
Collaborator

qiancai commented Mar 5, 2021

Similar to my comment in 4552, here are my thoughts. @morgo, PTAL. Thanks.

Background information:
Currently, all the latest TiDB documentation is branched from the master, so the documentation in the master contains all the historical version-specific information, which can help the document author to track all the changes, but it is not user-friendly.

Possible solution:
Comment out such version-specific information from the Markdown source file, and only keep the information of the current release.
Then for users, version-specific information is invisible on the website; for document authors, the version-specific information is kept there for tracking purposes.

@yikeke
Copy link
Contributor

yikeke commented Mar 16, 2021

Thanks. @morgo Your suggestion has been accepted (see #4552 (comment)). @qiancai will open a pull request to close this issue, and she'll involve you as a reviewer if you want.

@yikeke
Copy link
Contributor

yikeke commented Mar 16, 2021

/assign @qiancai

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
lifecycle/frozen Issues with this label will not be labeled as "stale".
Projects
None yet
Development

No branches or pull requests

5 participants