如何分布式创作 TiDB 6.0 用户手册?Book Rush 贡献指南来啦!

TiDB 6.0 试用体验官正火热招募中:fire:

一些社区小伙伴反应不知道如何贡献文章,这里特别给大家准备了详细的贡献指引,如果还是有问题请在评论区提问,我们来完善指引~

一、在专栏撰写和提交文章

1. 文章发布入口-社区专栏:https://tidb.net/blog

点击右上角发布文章

2. 撰写文章,为文章选择正确分类及 “6.x 实践”标签

  • 本地撰写完成,可直接复制黏贴提交
  • 直接撰写时,请随时点击下方的“保存草稿”,避免内容丢失

3. 文章审核,1-3个工作日内审核

社区的布道师组委会可能会对文章提出一些优化建议,按照建议优化后即可通过审核;这样即使你的文章不能入选 Book Rush,也可以被其他人看到和学习;

4. 文章发布奖励:

发布文章可获得 100-600经验值&积分,规则参考:专栏 - 专栏技术文章发布指南&奖励

5. Book rush 筛选

我们会定期 review “6.x 实践”标签下的文章,通过筛选的文章可以入选 Book Rush,运营小助手会邀请你来 Book rush 提交 pr

二、在电子书项目提交新文章

1. 登录/注册 GitHub (已有账号请忽略)

点击:https://github.com/ ,注册或者登录你的账号

如果已有账号,请点击右上角“Sign in”登录;没有账号则点击“Sign up”注册账号。

2. fork 电子书项目

点击:https://github.com/pingcap/book.tidb.net ,点击右上角的“fork”按钮

右上角还有 Star 按钮:为了表明你对项目的喜爱,可以点下小星星 :star2:

3. 为通过筛选的文章生成 md 文档

  • 方案一:把专栏文章复制黏贴到 https://markdown.com.cn/editor/ ,调整好格式之后,点击:文件-导出 Markdown ,把文章导出为 md 文档;
    image
  • 方案二(推荐):下载安装 Typora,在这里复制粘贴专栏文章,会将格式一键粘贴过来,调格式会简单很多。

3.1 md 文档格式说明

下面通过第一章第 1 节中的占位文章来说明下这里 md 文档的基本格式:

> ---
> title: 欢迎投稿
> hide_title: true
> ---

表头说明: 每个 md 文档中都必须添加这个表头,title 部分的文字可以自定义,对应了左侧目录栏中的章节显示,一级标题对应了右侧电子书中文章的大标题。

文档命名规则: 章节序号 - 文章英文名.md,比如你是某章节的第二篇文章,文章名为《 TiFlash 存储层概览》就可以命名为 2-tiflash-storage-overview.md。

作者简介: 建议文章开头加上作者的简介和社区主页的链接,是一个对外展示的好机会~

Markdown 基本语法学习:https://markdown.com.cn/basic-syntax/
更多格式可查看 Docusaurus 的 Markdown 特性:https://docusaurus.io/zh-CN/docs/markdown-features

4. 找到目录提交文章

Book Rush 电子书地址:https://github.com/pingcap/book.tidb.net/tree/main/website/book-rush

4.1 找到你要发布文章的一级目录

下图展示了 repo 中的文件夹和电子书实际展示出来的目录对应关系。比如 index.md 和书名对应,“1-features”文件夹对应了“第一章:TiDB 6.0 原理和特性”。

4.2 找到你要发布文章的二级目录

一级目录下的下一级目录中,以“4-performance”文件夹为例,也是类似的对应关系,“3-mpp-engine” 文件夹对应了“3. MPP 引擎计算性能提升”这一小节(如有不懂可以找运营小助手)

4.3 在二级目录下提交文章

  1. 第一步:找到你要上传的目录地址,在这个目录下点击“Upload files”

  1. 第二步: 点击“choose your files”, 上传本地 md 文档

image

  1. 第三步:写明文章标题和文章介绍(简短即可)

点击最下方“Commit changes”,这个文档就上传到你 fork 的项目中啦

5. 提交 PR

5.1 找到 fork 的电子书项目

Fork 成功后,点击右侧用户名下拉列表,进入 Your repositories 页面,就可以看到你 fork 的项目了

5.2 点击“Pull Request”标签页下的“New Pull Request”

跳转的页面中会自动比较你 fork 的项目和主仓间的差异,如果你确认这些差异没有误操作是你要提交内容,就点击“Create pull request”

5.3 描述 pr 提交内容,完成 pr 创建

然后,在跳出的页面中简明扼要的描述你要提交的内容,然后点击“Create pull request”,pr 即创建成找

5.4 等待 review

着急可联系运营小助手。

等待 reviewer 审核即可,你可以选择点击右侧的“request”,通知 reviewer 去 review 你的 pr,ta 会收到邮件提示。

5.5 取消 pr

最下方有“Close pull request”,点击即可取消 pr

6. 签署 CLA

如果你是第一次给 bookrush 贡献 pr,在你提交 pr 后,会收到签署 CLA 的提示,点击这个链接,按照指引操作签署即可。

image

7. pr review & merge

项目的 reviewer 在 review 你的 pr 时,可能会提一些修改的 comment。如果你对于这些 comment 有异议,可以在这里展开讨论;没有异议的话需要根据这些 comment 进行修改。

没有问题后,reviewer 会 merge 你的 pr,这时回到电子书页面,点击到对应的目录,你就可以看到自己刚刚提交的文章啦~https://tidb.net/book/book-rush

三、修改电子书中的文章

如果你想要修改自己提交的文章,或者发现其他人的文章中有错别字,都可以通过下面的操作来提交 pr。

1、找到文档所在的 GitHub 地址

首先,在电子书页面要修改的文章中,点击左下角“Edit this page”就会直接跳转到文档所在的 GitHub 地址。

2、 修改 fork 项目

点击“Edit this file”就可以对这个文档进行修改了

编辑完成后,拉到最下方,点击“Commit changes”,这些修改就提交在自己的仓库中了。建议在文本框内详细写清楚自己修改的内容,方便对自己的修改一目了然。

提示:当前只是自己的账户有修改,实际上电子书所在的项目是没有任何变动的。

3、 提交 pr,将修改同步到主库

参考步骤 5 提交 PR

四、Q&A

Q1、文章中的图片应该如何处理呢?

A:找到专栏中提交的文章,复制图片地址

按照 markdown 文档的格式,添加到文档中即可,如上图的图片在 md 文档中的代码如下:

![](https://tidb-blog.oss-cn-beijing.aliyuncs.com/media/image-1650972689089.png)

五一假期结束了,继续来卷TIDB 6吧:smiley:

每年一个大版本,优秀

感谢大佬们的创作:clap:

1赞