无论你是热爱技术的程序员,还是擅长书面表达的语言爱好者,亦或是纯粹想帮 TiDB 改进文档的热心小伙伴,都欢迎来为 TiDB 文档做贡献,一起打造更加易用友好的 TiDB 文档!
欢迎任何对提升 TiDB 文档质量、易用性、维护效率、翻译效率的贡献,比如,你可以在以下方面进行贡献:
下面主要介绍了如何为前两项做出贡献。
你可从以下任一方面入手:
- 修复文档格式(如标点、空格、缩进、代码块等)和错别字
- 修改过时或不当的内容描述
- 增加缺失的文档内容
- 回复或解决 issue 并提 PR 更新相关文档
- 其它改进
TiDB 中文文档的日常更新特别活跃,相应地,TiDB 英文文档也需要频繁更新。这一过程会涉及很多的中译英,即将 pingcap/docs-cn 仓库里已 merge 但尚未进行翻译处理的 Pull Request 翻译为英文,并提交 Pull Request 至 pingcap/docs 仓库中。具体的认领方式如下。
注意:
- 由于受众不同,TiDB 的中文文档与英文文档并非完全相同。但绝大多数情况下,中英版本会保持一致。
- 通常,TiDB 文档是先有中文版,后有英文版。但也有一小部分文档,是先有英文版,后有中文版。
- 快速上手资源一节中汇总了中英术语表和风格指南等参考文档,建议译前阅读。
目前,中文文档翻译任务以 docs-cn 仓库的 Pull Request (PR) 为形式,通过仓库管理员为 PR 加上的 labels 来认领翻译任务及追踪翻译任务状态。
你可以通过以下简单几步来认领并提交一个 PR 翻译任务:
注意:
关于下面步骤中所提到的 comment 式命令,详细说明请参考常用 bot 命令。
-
查看待认领 PR
打开 pingcap/docs-cn PR 翻译任务页面,即可看到所有打上了
translation/welcome
label 的 PR。这类 PR 无论是处于 open 还是 closed 状态,均可认领。 -
认领 PR
打开你想认领的 PR,拉到底部留下这条 comment:
/assign
,即可将此 PR 的翻译任务分配给自己。 -
修改 PR 标签
PR 认领成功后,继续在底部 comment 区域依次发送:
/remove-translation welcome
及/translation doing
,即可将右侧 label 栏中的translation/welcome
改为translation/doing
,之后你便可以开始翻译了。 -
翻译 PR 并提交
由于 TiDB 的中英文文档分别存放于 pingcap/docs-cn 和 pingcap/docs 中,并且两个仓库的文件结构完全对应。如果你是首次认领翻译任务,需先 fork docs 仓库,并将 fork 的 docs 仓库克隆到本地,然后找到源 PR 中对应的改动文件再开始翻译。翻译完毕后,创建新 PR,将翻译好的文件提交至 docs 仓库。具体操作步骤及更多参考资料可参见下文快速上手资源一节。
-
填写 PR 描述并修改标签
新建 PR 成功后,先按照模板说明完整填写 PR 描述,接着在底部发送:
/translation from-docs-cn
,为 PR 添加translation/from-docs-cn
标签,表明此 PR 是从中文翻译过来的。然后回到源 PR 依次发送:/remove-translation doing
及/translation done
,将源 PR 标签修改为translation/done
,表明翻译已完成。 -
分配 Reviewer(推荐,非必需)
每个 PR 都需要经过 Review 后才能合并,分配 Reviewer 一般由文档仓库管理员负责,但我们也十分欢迎你来主动承担这个任务。具体操作为:在新建的 PR 下发送
/cc @TomShawn @technical-reviewer
(将 technical-reviewer 替换为源 PR 作者的 GitHub ID),即可将 Review 任务分配给 docs 仓库管理员 @TomShawn 及源 PR 的作者。
最常见的贡献方式就是提 Pull Request 了,那么提交流程是怎样的,又需要遵守哪些规范呢?我们已准备好齐全的快速上手指南,你也可以查阅 docs-cn 现有的 Pull Request 作为参考。
-
Pull Request (PR) 提交 ⭐️
-
图片风格:Figma 快速上手教程
为确保文档图片风格统一,建议使用 Figma 绘制图片。绘制图片时,请参考模板提供的图形元素和配色方案。
TiDB 文档的修改需要遵循一定的流程,具体如下。考虑到有些小伙伴是纯语言背景,命令行的流程掌握起来可能需要花些时间,之后我们也会提供更适合小白上手的 GitHub Desktop 客户端版提交流程(在添加至这里之前,可暂时参考 lilin90 撰写的小白上手流程)。
注意:
目前 TiDB 主要维护以下几个版本的文档:dev(最新开发版,对应文档仓库的 master 分支)、v5.2、v5.1、v5.0、v4.0、v3.1、v3.0 以及 v2.1。提 Pull Request 前请务必考虑修改会影响的文档版本,并据此修改所有相应的版本。选择版本时,请参考版本选择指南。
首次在本仓库提 PR 时,请务必签署 Contributor License Agreement (CLA),否则我们将无法合并你的 PR。成功签署 CLA 后,可继续进行后续操作。
- 打开 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, v5.0, v4.0, v3.1, v3.0, v2.1),务必在 PR 描述框中勾选相应的版本,后续仓库管理员会为你的 PR 打上相应的 cherry-pick 标签。
TiDB 中文文档使用 Markdown 语言进行编写,为了保证文档质量和格式规范,你修改的文档需要遵循一定的 Markdown 规则。我们为 docs-cn 仓库设置了检测 markdown 文件规范的 CI check,即 markdownlint check。如果你提交的 PR 不符合规范,很可能无法通过 markdownlint check,最终导致无法合并 PR。
我们为 TiDB 中文文档提前设置了 25 条 markdownlint 规则,并附上了简单易懂的解释,强烈推荐花 5 分钟大致浏览一遍。
假如你提 PR 之前没有熟悉相关 Markdown 规范,提 PR 时遇到了 markdownlint check 失败,也不必担心,报错信息里会明确告诉你哪个文件的哪一行出了什么问题,根据提示在 PR 里更新一下文档内容即可搞定。
此外,你还可以选择在本地进行 markdownlint check:
./scripts/markdownlint [FILE...]
我们为 docs 和 docs-cn 仓库提前设置了一些命令语句,只要按照一定的格式在 PR 中留言,就能触发 bot 完成相应操作。下表列出了现阶段较为常用的命令、含义及示例。
命令 | 含义 | 示例 |
---|---|---|
/label |
给 PR 添加 label,多个 label 间需要用逗号分隔。如果 label 中有斜线 / ,则命令为 /[label 的第一个单词] [label 其他部分] |
/label contribution ,/translation from-docs |
/remove-label |
删除 PR label。如果 label 中有斜线 / ,则命令为 /remove-[label 的第一个单词] [label 其他部分] |
/remove-label contribution ,/remove-translation welcome |
/assign |
将 PR 分配给指定的人,需 @指定用户的 GitHub ID,多个 GitHub ID 间用逗号分隔。如果想要将 PR 分配给自己,/assign 后可不跟 GitHub ID。 |
/assign @CharLotteiu |
/unassign |
移除 PR 之前指定的 assignee。 | /unassign @CharLotteiu |
/cc |
将 PR 分配给指定的 reviewer,需 @指定用户的 GitHub ID,多个 GitHub ID 间用逗号分隔。 | /cc @TomShawn, @yikeke |
/uncc |
移除 PR 之前指定的 reviewer。 | /uncc @TomShawn |
创建 Pull Request 时,你需要在 Pull Request 的描述模版中选择文档改动适用的版本分支。
如果你的 PR 改动符合以下任一情况,推荐只选择 master 分支。此 PR 的改动在合并后将显示到官网文档 Dev 页面,在下一次 TiDB 发新版本时将显示到对应版本的文档页面。
- 完善和优化文档内容,例如补充缺失或不完整的信息。
- 修正不准确或错误的文档内容,例如默认值错误、描述不准确、示例错误、拼写错误等。
- 重新组织现有文档的某个局部,例如“部署标准集群”、“数据迁移”、“TiDB 生态工具”等。
如果你的 PR 改动符合以下任一情况,请选择 master 分支以及受影响的 release 分支:
- 涉及与版本相关的功能行为变化。
- 涉及与版本相关的兼容性变化,例如更改某个配置项或变量的默认值。
- 修复文档页面的渲染或显示错误。
- 修复文档内的死链。
加入 Slack channel:#sig-docs