Welcome to TiDB documentation! We are excited about the prospect of you joining TiDB Community.
You can start from any one of the following items to help improve TiDB Docs at the PingCAP website:
- Fix typos or format (punctuation, space, indentation, code block, etc.)
- Fix or update inappropriate or outdated descriptions
- Add missing content (sentence, paragraph, or a new document)
- Translate docs changes from English to Chinese
- Submit, reply to, and resolve docs issues
- (Advanced) Review Pull Requests created by others
Before you contribute, please take a quick look at some general information about TiDB documentation maintenance. This can help you to become a contributor soon.
-
Diagram Style: Figma Quick Start Guide
To keep a consistent style for diagrams, we recommend using Figma to draw or design diagrams. If you need to draw a diagram, refer to the guide and use shapes or colors provided in the template.
We provide several doc templates for you to use to create documentation that aligns with our style.
Please check out these templates before you submit a pull request:
Currently, we maintain the following versions of TiDB documentation, each with a separate branch:
Docs branch name | Version description |
---|---|
master branch |
the latest development version |
release 6.1 branch |
the 6.1 LTS (Long-Term Support) version |
release 6.0 branch |
the 6.0 Development Milestone Release |
release-5.4 branch |
the 5.4 stable version |
release-5.3 branch |
the 5.3 stable version |
release-5.2 branch |
the 5.2 stable version |
release-5.1 branch |
the 5.1 stable version |
release-5.0 branch |
the 5.0 stable version |
release-4.0 branch |
the 4.0 stable version |
release-3.1 branch |
the 3.1 stable version |
release-3.0 branch |
the 3.0 stable version |
release-2.1 branch |
the 2.1 stable version |
Note:
Previously, we maintain all versions in the
master
branch, with directories likedev
(the latest development version),v3.0
and so on. Each docs version is updated very frequently and changes to one version often apply to another version or other versions as well.Since February 21, 2020, to reduce manual editing and updating work among versions, we have started to maintain each version in a separate branch and introduced sre-bot (now ti-chi-bot) to automatically file PRs to other versions as long as you add corresponding cherry-pick labels to your PR.
-
If your changes apply to only one docs version, just submit a PR to the corresponding version branch.
-
If your changes apply to multiple docs versions, you don't have to submit a PR to each branch. Instead, after you submit your PR, trigger the ti-chi-bot to submit a PR to other version branches by adding one or several of the following labels as needed. Once the current PR is merged, ti-chi-bot will start to work.
needs-cherry-pick-6.1
label: ti-chi-bot will submit a PR to therelease-6.1
branch.needs-cherry-pick-6.0
label: ti-chi-bot will submit a PR to therelease-6.0
branch.needs-cherry-pick-5.4
label: ti-chi-bot will submit a PR to therelease-5.4
branch.needs-cherry-pick-5.3
label: ti-chi-bot will submit a PR to therelease-5.3
branch.needs-cherry-pick-5.2
label: ti-chi-bot will submit a PR to therelease-5.2
branch.needs-cherry-pick-5.1
label: ti-chi-bot will submit a PR to therelease-5.1
branch.needs-cherry-pick-5.0
label: ti-chi-bot will submit a PR to therelease-5.0
branch.needs-cherry-pick-4.0
label: ti-chi-bot will submit a PR to therelease-4.0
branch.needs-cherry-pick-3.1
label: ti-chi-bot will submit a PR to therelease-3.1
branch.needs-cherry-pick-3.0
label: ti-chi-bot will submit a PR to therelease-3.0
branch.needs-cherry-pick-2.1
label: ti-chi-bot will submit a PR to therelease-2.1
branch.needs-cherry-pick-master
label: ti-chi-bot will submit a PR to themaster
branch.
For how to choose the docs versions, refer to Guideline for choosing the affected version(s).
-
If most of your changes apply to multiple docs versions but some differences exist among versions, you still can use cherry-pick labels to let ti-chi-bot create PRs to other versions. After the PR to another version is successfully submitted by ti-chi-bot, you can make changes to that PR.
Please perform the following steps to create your Pull Request to this repository. If don't like to use commands, you can also use GitHub Desktop, which is easier to get started.
Note:
This section takes creating a PR to the
master
branch as an example. Steps of creating PRs to other branches are similar.
Your Pull Requests can only be merged after you sign the Contributor License Agreement (CLA). Please make sure you sign the CLA before continuing.
- Visit the project: https://github.com/pingcap/docs
- Click the Fork button on the top right and wait it to finish.
cd $working_dir # Comes to the directory that you want put the fork in, for example, "cd ~/Documents/GitHub"
git clone [email protected]:$user/docs.git # Replace "$user" with your GitHub ID
cd $working_dir/docs
git remote add upstream [email protected]:pingcap/docs.git # Adds the upstream repo
git remote -v # Confirms that your remote makes sense
-
Get your local master up-to-date with upstream/master.
cd $working_dir/docs git fetch upstream git checkout master git rebase upstream/master
-
Create a new branch based on the master branch.
git checkout -b new-branch-name
Edit some file(s) on the new-branch-name
branch and save your changes. You can use editors like Visual Studio Code to open and edit .md
files.
git status # Checks the local status
git add <file> ... # Adds the file(s) you want to commit. If you want to commit all changes, you can directly use `git add.`
git commit -m "commit-message: update the xx"
See Commit Message Style.
# While on your new branch
git fetch upstream
git rebase upstream/master
git push -u origin new-branch-name # "-u" is used to track the remote branch from origin
- Visit your fork at https://github.com/$user/docs (replace
$user
with your GitHub ID) - Click the
Compare & pull request
button next to yournew-branch-name
branch to create your PR. See Pull Request Title Style.
Now, your PR is successfully submitted! After this PR is merged, you will automatically become a contributor to TiDB documentation.
When you create a Pull Request, you need to choose the release version to which your document change applies in the description template on your Pull Request page.
If your change fits one of the following situations, it is recommended to CHOOSE THE MASTER BRANCH ONLY. After the PR is merged, the change will be soon displayed on the Dev page of the PingCAP documentation website. After the next major or minor version of TiDB is released, the change will also be displayed on the website page for the new version.
- Relates to a documentation enhancement, such as supplementing missing or incomplete document contents.
- Fixes inaccurate or incorrect document contents, including values, descriptions, examples, or typos.
- Involves a documentation refactor in a specific topic module.
If your change fits one of the following situations, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER:
- Involves a feature behavior change that relates to a specific version.
- Involves a compatibility change, including changing the default value of a configuration item or a system variable.
- Fixes format to resolve a display error
- Fixes broken links
Join the TiDB Internals forum for discussion.