Foreword
一般来讲，开源项目都非常欢迎 Technical Writer 来帮助改善其文档。而对于 Technical Writer 来说，这也是锻炼自己、提升个人专业能力的一个好机会，尤其是对于那些想利用业余时间来拓展知识面、提升个人竞争力的小伙伴来说。
前几日，在 Technical Writer 想参与开源项目为文档做贡献，需提前掌握哪些知识？中跟大家分享了一些要参与开源项目的文档需掌握的一些基础背景知识。这一篇将以 GitHub 官方客户端 GitHub Desktop 为例，跟大家分享简单易上手的具体操作步骤。
关于开源项目的文档，本文以 PingCAP 公司在做的开源分布式 NewSQL 数据库 TiDB 的中文文档为例。不同的项目在流程规范上或许有一些区别，但本质上大同小异。如果你想参与另外某个开源项目的文档，也可以参考本文的操作步骤，同时注意该项目是否有一些特定的规范需要遵守。
- TiDB 项目：https://github.com/pingcap/tidb
- TiDB 文档：
下文步骤遵循了 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。
- 如果你不知道该让谁 Review，可以去所修改文档的 GitHub 页面中看下 History，了解下该文档的作者，以及之前有哪些小伙伴修改过。还可以去该 Repository 的主页面，点击 contributors，看下比较活跃的 contributor 是哪些同学。然后可以添加他们来 review。
- 如果你知道 Reviewer 的 GitHub ID，也可以在 Leave a comment 框里通过 @ID 的方式邀请其 Review。
5. 点击 Create pull request 即创建了一个 Pull Request。
点击之后：
该示例 PR 链接：https://github.com/pingcap/docs-cn/pull/1294
Afterword
如果在创建 PR 之后你又想修改一些地方，可参考以下步骤：
- 在 GitHub Desktop 客户端界面的 Current Branch 中选择该 Pull Request 对应的 Branch。
- 点击 Fetch origin 拉取远程内容，以确保本地 Branch 与远程 Branch 的内容保持最新一致。
- 编辑需要修改的文件。
- 写一个 Commit message 提交修改。
- 点击 Push origin 将修改推至远程 Branch 即可。
如果 Reviewer 以 Suggestion 模式添加了 Comments，可以直接在网页端接受建议，也可以在本地修改推至远程。
开源项目的文档需要专业的 Technical Writer 来帮助其不断改进完善，如格式、表述、逻辑组织等；而对于 Technical Writer 来说，这也是一个很好的体验和锻炼的机会。
如果你对此感兴趣，但还没想好参与什么样的开源项目，不妨从这两个关于数据库的 repository 开始体验：
如果你真的付诸了行动，往以上两个 repository 里提了 Pull Request，可以直接 @我 Review。我的 GitHub ID 是 lilin90 (https://github.com/lilin90)。
你可能想读：
技术文档诞生记 | 完整的技术写作流程是怎样的？
Technical Writer 可提供的交付物有哪些？
GitHub + Markdown 的新轻型技术写作模式速览
GitHub + Markdown 的技术文档方案深度解析
Technical Writer 日常工作中好用的小工具
技术传播人士应该知道的色彩搭配常识
如何使用颜色来提高技术文档的可读性？
Technical Writer 如何 Review 技术文档？| 重细节+全局观
技术翻译需要有 Technical Writer 的 sense
深度解析关于技术翻译的六个认知误区
如何让你的内容输出更加专业更有设计感？
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？（一）
有哪些适合技术传播从业者关注的优质博客？（二）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（上篇）
经验分享 | 来自 11 位 Technical Writer 前辈的职业发展建议（下篇）
技术传播沙龙精彩分享 | 高校老师与行业大牛谈“互联网技术写作”
英语技术文档的标题到底该大写还是小写？
不同阶段如何应对 Technical Writer 的职业顾虑或烦恼？
如何使用正则表达式批量添加和删除字符？
英语技术文档中如何正确使用时态？
英语技术文档中如何正确使用人称？
英语技术文档中如何正确使用无序列表和有序列表？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
如何为 Markdown 文件自动生成目录？
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
Technical Writer 需要 Technical 到会写代码吗？
如何利用 GitHub Pages 和 Hugo 轻松搭建个人博客？
写在入职技术型创业公司 PingCAP 一个月之后
揭秘 Technical Writer 的工作环境 | 加入 PingCAP 五个月的员工体验记
-END-
