Technical Writer 如何参与开源项目的文档，以不断

2019-06-18 本文已影响1人 Lilian_Lee

Foreword

一般来讲，开源项目都非常欢迎 Technical Writer 来帮助改善其文档。而对于 Technical Writer 来说，这也是锻炼自己、提升个人专业能力的一个好机会，尤其是对于那些想利用业余时间来拓展知识面、提升个人竞争力的小伙伴来说。

前几日，在 Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？中跟大家分享了一些要参与开源项目的文档需掌握的一些基础背景知识。这一篇将以 GitHub 官方客户端 GitHub Desktop 为例，跟大家分享简单易上手的具体操作步骤。

关于开源项目的文档，本文以 PingCAP 公司在做的开源分布式 NewSQL 数据库 TiDB 的中文文档为例。不同的项目在流程规范上或许有一些区别，但本质上大同小异。如果你想参与另外某个开源项目的文档，也可以参考本文的操作步骤，同时注意该项目是否有一些特定的规范需要遵守。

TiDB 项目：https://github.com/pingcap/tidb
TiDB 文档：
- 中文：https://github.com/pingcap/docs
- 英文：https://github.com/pingcap/docs-cn

下文步骤遵循了 PingCAP 的 Pull Request 提交规范，例如：如何写 commit message 和 Pull Request title 等。这些规范细则均是公开的，如果你想详细了解，可以访问该链接：https://github.com/pingcap/community/blob/master/commit-message-pr-style.md

注意：

本文步骤中的截图是 macOS 版的，如果你用的是 Windows 系统，在按照本文描述的步骤操作时，看到的页面可能会略有不同。不过操作流程是一致的，大家知道即可。
客户端的界面可能会不断优化调整，笔者发现与一年前相比已经有一些细节单词的变化，但总体来讲还是一致的，不会影响步骤的理解。下文配图截于 2019 年 5 月 4 日，如果你使用的时候发现界面又与本文截图不完全一样了，也不必困惑。

第 1 步：下载、安装并登录 GitHub Desktop。

1. 打开官方下载页面 (https://desktop.github.com/) 下载 GitHub Desktop，然后完成安装。

2. 点击 GitHub Desktop 图标，用你的账号和密码完成登录。

如果你还没有 GitHub 账号，去官网注册一个即可，地址：https://github.com/

第 2 步：Fork 你想参与的项目仓库 (repository)。

1. 打开项目页面 (https://github.com/pingcap/docs-cn)，点击右上角的 Fork即可。

2. Fork 完成后，你可以在个人主页的 Repositories 下看到你刚刚 Fork 的 Repository。

第 3 步：将已 Fork 的远程仓库 Clone 至本地。

1. 打开 GitHub Desktop，点击 File > Clone Repository。

2. 在 GitHub.com 中的 Your Repositories 下，选择需要 Clone 至本地的项目，点击右下角的 Clone。

你可以使用默认的 GitHub 项目保存路径，也可以点击 Choose 自定义保存路径。

第 4 步：确保本地仓库与上游仓库内容一致。

这一步是为了保证在最新版本的内容上进行修改，以避免一些不必要的冲突。

1. 点击 Current Repository，选择要修改的项目。

2. 在 Current Branch 下选择 master，然后点击 Fetch origin，等待 Fetch 完成。

3. 点击顶部菜单栏的 Branch > Merge into Current Branch。

4. 选择 upstream/master，点击 Merge upstream/master into master。

如果本地仓库的 master 已与上游仓库的 master 内容一致，在选择 upstream/master 后，界面底部会有当前 master branch 已为最新的提示。而且，Merge upstream/master into master 会呈现浅蓝色。此时，就不必再进行内容同步了，可直接进入第 5 步。

5. 点击 Push origin，将刚刚 Merge 到本地 master branch 的 Commit 推至远程仓库。

Push 完成之后，本地仓库 master branch 的内容便与上游仓库的 master branch 一致了。可以打开自己 Fork 的该 Repository 页面查看（我的页面为 https://github.com/lilin90/docs-cn），会看到 This branch is even with pingcap:master.

第 5 步：新建一个 Branch。

1. 点击 Current Branch > New Branch。

2. 输入新的 Branch 名称，然后点击 Create Branch 即可。

Branch 的名称使用几个关键词即可，不需要很长；通常，各单词之间可使用连字符进行连接。

第 6 步：使用 Markdown 编辑器修改文档。

1. 使用 Visual Studio Code 打开需要修改的文件。

2. 编辑并保存，可在 GitHub Desktop 中直观地看到修改情况。

你可以修改一个文件，也可以增加一个新的文件，或者删除一个现有文件。

第 7 步：将修改 Commit 到新建的 Branch。

1. 在 GitHub Desktop 界面左下角的输入框里，为你的修改写一个 Commit message 和 Description。

Commit message 即对修改的简要总结，是必须的。关于如何写好 Commit message，PingCAP 公开了一套规范，参见：https://github.com/pingcap/community/blob/master/commit-message-pr-style.md
Description 用于对你的修改进行更多细节描述，如相关的 Pull Request 或 Issue 链接，或关于 Why/What 等的描述。简单的修改可以不填此项。

2. 点击 Commit to XX (the branch you created)，即可将修改提交至新建的 Branch。

第 8 步：将新建的 Branch 推至远程仓库。

点击 GitHub Desktop 界面右上角的 Publish branch 将包含修改的新建 Branch 推至远程仓库。

第 9 步：创建一个 Pull Request。

这是最后一步啦！完成这一步，就可以将自己对文档的修改提交到上游仓库了。

1. 在浏览器里打开你 Fork 的 Repository 页面或者上游 Repository 页面。

例如：https://github.com/lilin90/docs-cn 或者 https://github.com/pingcap/docs-cn

可以看到黄色突出显示的刚刚推上来的 Branch 提示。

2. 点击 Compare and pull request。

或

3. 为该 Pull Request 写一个 Title 和 Description。

Title 为必填项。如果你的 Commit message 可以涵盖所有修改，可以使用它作为 Title；如果不能，则另写一个更具概括性的。
Description 为非必填项。通常需要在 Leave a comment 框里具体描述一下该 Pull Request 所做的修改和细节，如相关的 Pull Request 或 Issue 链接，主要做了哪些修改，以方便他人 Review。对于特别简单的 Pull Request，如本文的示例，可不填。

关于如何写好 Pull Request 的 Title 和 Description，PingCAP 也公开了一套规范，参见：https://github.com/pingcap/community/blob/master/commit-message-pr-style.md#pull-request-title-style

4. 点击右侧的 Reviewers，选择你想添加的 Reviewer。

image

如果你不知道该让谁 Review，可以去所修改文档的 GitHub 页面中看下 History，了解下该文档的作者，以及之前有哪些小伙伴修改过。还可以去该 Repository 的主页面，点击 contributors，看下比较活跃的 contributor 是哪些同学。然后可以添加他们来 review。
如果你知道 Reviewer 的 GitHub ID，也可以在 Leave a comment 框里通过 @ID 的方式邀请其 Review。

5. 点击 Create pull request 即创建了一个 Pull Request。