You can start from any one of the following items to help improve TiDB Docs at the PingCAP website:
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.
Currently, we maintain four versions of TiDB documentation, each with a separate branch:
|Docs branch name||Version description|
||the latest development version|
||the 4.0 Beta version|
||the 3.1 RC version|
||the 3.0 stable version|
||the 2.1 stable version|
Previously, we maintain all versions in the
masterbranch, with directories like
dev(the latest development version),
v3.0and 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 introduce sre-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 sre-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, sre-bot will start to work.
needs-cherry-pick-4.0label: sre-bot will submit a PR to the
needs-cherry-pick-3.1label: sre-bot will submit a PR to the
needs-cherry-pick-3.0label: sre-bot will submit a PR to the
needs-cherry-pick-2.1label: sre-bot will submit a PR to the
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 sre-bot create PRs to other versions. After the PR to another version is successfully submitted by sre-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 command, you can also use GitHub Desktop, which is easier to get started.
This section takes creating a PR to the
masterbranch as an example. Steps of creating PRs to other branches are similar.
cd $working_dir # Comes to the directory that you want put the fork in, for example, "cd ~/Documents/GitHub" git clone email@example.com:$user/docs.git # Replace "$user" with your GitHub ID cd $working_dir/docs git remote add upstream firstname.lastname@example.org: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
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
$userwith your GitHub ID)
Compare & pull requestbutton next to your
new-branch-namebranch 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.
Join the Slack channel: #sig-docs