无论你是热爱技术的程序员，还是擅长书面表达的语言爱好者，亦或是纯粹想帮 TiDB 改进文档的热心小伙伴，都欢迎来为 TiDB 文档做贡献，一起打造更加易用友好的 TiDB 文档！
你既可以帮助完善中文文档，也可以将中文文档的更新翻译为英文，并成为英文文档的 contributor。
你可从以下任一方面入手：
- 修复文档格式（如标点、空格、缩进、代码块等）和错别字
- 修改过时或不当的内容描述
- 增加缺失的文档内容
- 回复或解决 issue 并提 PR 更新相关文档
- 其它完善
TiDB 中文文档的日常更新特别活跃，相应地，TiDB 英文文档 也需要进行频繁的更新。这一过程会涉及很多的中译英，即将 pingcap/docs-cn 里已 merge 但尚未进行翻译处理的 Pull Request 翻译为英文，并提交 Pull Request 至 pingcap/docs 中。具体的认领方式即将公布。
注意：
- 由于受众不同，TiDB 的中文文档与英文文档并非完全相同。但绝大数情况下，中英版本会保持一致。
- 通常，TiDB 文档是先有中文版，后有英文版。但也有一小部分文档，是先有英文版，后有中文版。
最常见的贡献方式就是提 Pull Request 了，那么提交流程是怎样的，又需要遵守哪些规范呢？我们已准备好齐全的快速上手指南，你也可以查阅 docs-cn 现有的 Pull Request 作为参考。
- Pull Request (PR) 提交 ⭐️
- 必须遵循的 Markdown 规范 ⭐️
- 代码注释规范
- PingCAP 中文文档风格指南
- TiDB 中文用户文档模板
TiDB 中文文档使用 Markdown 语言进行编写，为了保证文档质量和格式规范，你修改的文档需要遵循一定的 Markdown 规则。我们为 docs-cn 仓库设置了检测 markdown 文件规范的 CI check，即 markdownlint check。如果你提交的 PR 不符合规范，很可能无法通过 markdownlint check，最终导致无法合并 PR。
假如你提 PR 之前没有熟悉相关 Markdown 规范，提 PR 时遇到了 markdownlint check 失败，也不必担心，报错信息里会明确告诉你哪个文件的哪一行出了什么问题，根据提示在 PR 里更新一下文档内容即可搞定。此外，你还可以选择在本地进行 markdownlint check：
./scripts/markdownlint [FILE...]👇以下是我们为 TiDB 中文文档提前设置的 26 条 markdownlint 规则，附上了简单易懂的解释，相信你花几分钟快速浏览一遍 🤓即可基本掌握。
| NO. | 规则 | 描述 |
|---|---|---|
| 1 | MD001 - Heading levels should only increment by one level at a time | 标题从一级开始递增使用，禁止跳级使用。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。 |
| 2 | MD003 - Heading style | 标题必须统一使用 ATX 风格，即在标题前加 # 号来表示标题级别。 |
| 3 | MD018 - No space after hash on atx style heading | 标题的引导符号 # 后必须空一格再接标题内容。 |
| 4 | MD019 - Multiple spaces after hash on atx style heading | 标题的引导符号“#”后只能空一格后再接标题内容，不能有多个空格。 |
| 5 | MD023 - Headings must start at the beginning of the line | 标题必须出现在一行行首，即标题的 # 号前不能有任何空格。 |
| 6 | MD026 - Trailing punctuation in heading | 标题末尾仅能出现中英文问号、反引号、中英文单双引号等符号。其余如冒号、逗号、句号、感叹号等符号均不能在标题末尾使用。 |
| 7 | MD022 - Headings should be surrounded by blank lines | 标题上下均须空一行。 |
| 8 | MD024 - Multiple headings with the same content | 文档中不能连续出现内容重复的标题，如一级标题为 # TiDB 架构，紧接着的二级标题就不能是 # TiDB 架构。如果不是连续的标题，则标题内容可重复。 |
| 9 | MD025 - Multiple top level headings in the same document | 文档中只能出现一个一级标题。一级标题前的元数据（写明了 title 和 category）不会违反该规则。 |
| 10 | MD041 - First line in file should be a top level heading | 文档正文一开始必须是一级标题。这条规则会自动忽略文档中头几行的元数据，直接检查后面是否有一级标题。 |
| 11 | MD007 - Unordered list indentation | 一般来说，除 TOC.md 文件可缩进 2 个空格外，其余所有 .md 文件每缩进一级，默认须缩进 4 个空格。 |
| 12 | MD009 - Trailing spaces | 行尾禁止出现多余的空格。 |
| 13 | MD010 - Hard tabs | 文档中（包括代码块内）禁止出现 Tab 制表符，如需缩进，必须统一用空格代替。 |
| 14 | MD012 - Multiple consecutive blank lines | 禁止出现连续的空行。 |
| 15 | MD027 - Multiple spaces after blockquote symbol | 块引用符号 > 后禁止出现多个空格，只能使用一个空格，后接引用内容。 |
| 16 | MD029 - Ordered list item prefix | 使用有序列表时，必须从 1 开始，按顺序递增。 |
| 17 | MD030 - Spaces after list markers | 使用列表时，每一列表项的标识符（+、-、* 或数字）后只能空一格，后接列表内容。 |
| 18 | MD032 - Lists should be surrounded by blank lines | 列表（包括有序和无序列表）前后必须各空一行。 |
| 19 | MD031 - Fenced code blocks should be surrounded by blank lines | 代码块前后必须各空一行。 |
| 20 | MD034 - Bare URL used | 文档中禁止出现裸露的 URL。如果希望用户能直接点击并打开该 URL，则使用一对尖括号 (<URL>) 包裹该 URL。如果由于特殊情况必须使用裸露的 URL，不需要用户通过点击打开，则使用一对反引号 (`URL`) 包裹该 URL。 |
| 21 | MD037 - Spaces inside emphasis markers | 使用加粗、斜体等强调效果时，在强调标识符内禁止出现多余的空格。如不能出现 `** 加粗文本 **`。 |
| 22 | MD038 - Spaces inside code span elements | 单个反引号包裹的代码块内禁止出现多余的空格。如不能出现 ` 示例文本 `。 |
| 23 | MD039 - Spaces inside link text | 链接文本两边禁止出现多余的空格。如不能出现 [ 某链接 ](https://www.example.com/)。 |
| 24 | MD042 - No empty links | 链接必须有链接路径。如不能出现[空链接]()或[空链接](#)等情况。 |
| 25 | MD045 - Images should have alternate text (alt text) | 图片链接必须添加描述文本（即 []() 的 [] 内必须有描述文字），这是为了让无法加载出图片的人看到图片的描述性文字。 |
| 26 | MD046 - Code block style | 文档中的代码块统一使用三个反引号 ``` 进行包裹，禁止使用缩进四格风格的代码块。 |
TiDB 文档的修改需要遵循一定的流程，具体如下。考虑到有些小伙伴是纯语言背景，命令行的流程掌握起来可能需要花些时间，之后我们也会提供更适合小白上手的 GitHub Desktop 客户端版提交流程（在添加至这里之前，可暂时参考 lilin90 撰写的小白上手流程）。
注意：
目前 TiDB 主要维护四个版本的文档：dev（最新开发版），v3.1（3.1 Beta 版），v3.0（最新稳定版），v2.1（最新 2.1 版）。提 Pull Request 前请务必考虑修改会影响的文档版本，并据此修改所有相应的版本。
- 打开 pingcap/docs-cn 项目仓库：https://github.com/pingcap/docs-cn
- 点击右上角的 Fork 按钮，等待 Fork 完成即可。
cd $working_dir # 将 $working_dir 替换为你想放置 repo 的目录。例如，`cd ~/Documents/GitHub`
git clone git@github.com:$user/docs-cn.git # 将 `$user` 替换为你的 GitHub ID
cd $working_dir/docs-cn
git remote add upstream git@github.com:pingcap/docs-cn.git # 添加上游仓库
git remote -v
-
确保本地 master branch 与 upstream/master 保持最新。
cd $working_dir/docs-cn git fetch upstream git checkout master git rebase upstream/master -
基于 master branch 新建一个 branch，名称格式为：aaa-bbb-ccc。
git checkout -b new-branch-name
在建好的 new-branch-name branch 上进行编辑，可使用 Markdown 编辑器（如 Visual Studio Code）打开 docs-cn repo，对相应文档进行增、删，或修改，并保存你的修改。
git status
git add <file> ... # 如果你想提交所有的文档修改，可直接使用 `git add .`
git commit -m "commit-message: update the xx"
# 在新建 branch 上
git fetch upstream
git rebase upstream/master
git push -u origin new-branch-name
- 打开你 Fork 的仓库：https://github.com/$user/docs-cn（将
$user替换为你的 GitHub ID） - 点击
Compare & pull request按钮即可创建 PR。参考如何写 PR title 和描述。
注意：
- 如果你的修改影响多个文档版本 (dev, *v4.0, v3.1, v3.0, v2.1)，务必在 PR 描述框中勾选相应的版本，或者在页面右侧选择相应的 label (dev, *v4.0, v3.1, v3.0, v2.1) 来注明。v4.0 为尚未发布的新版本。
- 如果你的修改也同样适用于英文版文档，需要在提 PR 时添加 label
pending-aligning；也非常欢迎同时更新中文版和英文版。