前段时间有幸参与了开源社区的活动，并且借由 Apache Pulsar 项目实践了 GitHub + MarkDown 的文档开发。在与开源社区的童鞋进行交流的过程中了解到，对于非技术专业的TCer，即便对于社区贡献具有热情，但往往会被看似复杂的工具和流程“劝退”。那么在这里，我会基于个人的实践与体验，分享一下自认为“最简”的操作说明。

在本文中，会按照以下顺序进行介绍：

1. 整体流程及难点说明：概览整体流程，并且指出操作难点。

2. 预备知识和准备工作：在部署和使用 GitHub + MarkDown 进行文档开发的过程中，需要掌握的基础知识，及准备工作。

3. 操作界面说明：整体流程涉及的操作界面简介。

4. 工作环境部署说明：将本地电脑部署为参与开源项目的终端。通常，在项目存续过程中，工作环境仅需部署一次；如工作环境损坏，可直接删除本地文件后，进行重新部署。

5. 日常工作流程说明：在工作环境已部署的情况下，每一轮修改，都需要完整执行日常工作流程，实现闭环。

那么接下来，就让我们具体看看。

整体流程及难点说明

整体流程

从整体来看，使用 GitHub + MarkDown 参与开源项目主要包括以下步骤：

图片说明：

• 实线：操作步骤及数据方向。

• 序号：操作步骤。

• 虚线上方：GitHub 云端操作。

• 虚线下方：本地操作。

• 虚线切割：线上/线下传输操作。

1. fork：创建备份，将 apache/pulsar 目录复制为个人  <user>/pulsar 目录。后续针 pulsar 项目的修改基于个人目录实施。

2. clone：复制个人 <user>/pulsar 目录的项目文件下载到本地。

3. fetch upstream：建立本地文件与 apache/pulsar 的同步更新，确保后续使用最新版本文件进行修改。

4. branch：创建修改分支。

5. edit：使用编辑工具修改文件内容。

6. commit：文件修改完成后，提交文件。

7. push：上传文件至个人 <user>/pulsar 目录。

8. pull request：提交修改 PR 至 apache/pulsar，待确认无误后合入 apache/pulsar。

其中：1～3为工作环境部署；4～8为修改流程。后续将在“工作环境部署说明”和“日常工作流程说明”2个部分进行详细说明。

难点说明

1. 工作环境部署涉及较多命令行操作，对于非技术用户可能不是特别友好，如果有条件，不妨请技术小伙伴协助完成；不过如果尝试独立完成，一定会获得满满的成就感，相信你可以的。

2. 在日常工作中，需要特别注意文件的版本控制，避免在提交 pull request 时，出现混淆。具体说明参见：日常工作流程说明 > 1. branch

预备知识和准备工作

在进行后续操作说明时涉及以下内容，但不会展开说明，需要大家预先了解。

1. 在进行工作环境部署时，涉及命令行操作。需了解：

• 如何调出命令行对话框。

• 如何使用 DOS 命令定位至指定目录。相关命令包括：cd, cd.., cd\, <盘符>, cd <目录>,dir

2. 注册 GitHub 用户。

链接：https://github.com/join

3. 安装 GitHub 桌面版。

链接：https://desktop.github.com/

操作界面说明

在所有操作过程中，涉及以下三种界面：

• GitHub 的 Web 页面：用于 GitHub 云端操作。例如：fork、pull request 等。

• 命令行页面：推荐用于工作环境部署。

• GitHub 桌面版：推荐用于日常工作流程。

GitHub 的 Web 页面

命令行页面

GitHub 桌面版

准备好了吗？下面我们就要正式进入操作流程了，祝你好运！

工作环境部署说明

工作环境部署操作包括：

1. fork：创建备份，将 apache/pulsar 目录复制为个人  <user>/pulsar 目录。后续针对 pulsar 项目的修改基于个人目录实施。

2. clone：复制个人 <user>/pulsar 目录的项目文件下载到本地。

3. fetch upstream：建立本地文件与 apache/pulsar 的同步更新，确保后续使用最新版本文件进行修改。

1. fork

操作界面：GitHub 的 Web 页面

1） 访问 apache/pulsar 项目页面：
          链接：https://github.com/apache/pulsar

2） 点击 fork 按钮。

fork 操作完成后， apache/pulsar 和 <user>/pulsar 被加入至本人的 Repositories 表。

2. clone

操作界面：GitHub 桌面版

1） 点击 Current repository > Add > Clone repository，打开 Clone a repository 对话框。

2） 在 Clone a repository 对话框：
          指定 Your repository 为 <user>/pulsar；
          指定 Local path 为指定本地目录；
          点击 Clone 按钮。

clone 操作完成后，<user>/pulsar 的项目文件下载至本地指定目录。

3. fetch upstream

操作界面：命令行

1） 调出系统命令行操作界面。

说明：由于不同系统调出系统命令行操作界面的方法不同，请自行搜索解决。本文以 Window 10 操作系统为例：

点击“开始” > “搜索”按钮；

搜索“cmd”，打开“命令提示符”窗口。

2） 使用 DOS 命令定位至工作目录路径。例如：

D:\myFolder\PULSAR\Repository\pulsar>

3） 在工作路径下，依次执行以下命令：

#设置本地文件与 apache/pulsar 同步#
git remote add upstream https://github.com/apache/pulsar.git#验证同步设置#
git remote -v#正确返回信息#
origin    https://github.com/$user/pulsar.git (fetch)
origin    https://github.com/$user/pulsar.git (push)
upstream  https://github.com/apache/pulsar (fetch)
upstream  https://github.com/apache/pulsar (push)#设置本地master分支同步#
git checkout master
git fetch upstream
git rebase upstream/master
git push origin master

祝贺你，你已经成功完成了本地工作环境部署。

日常工作流程说明

每次实施修改，都要按照日常工作流程操作闭环，具体内容包括：

1. branch：创建修改分支。
   注意：
   1) 一个 issue 对应一个 branch。
   2) 每次修改必须创建修改分支，不可在 master 分支上直接实施修改。

2. edit：使用编辑工具修改文件内容。

3. commit：文件修改完成后，提交文件。
   注意：提交文件时，需确认提交到正确的修改分支。

4. push：上传文件至个人 <user>/pulsar 目录。

5. pull request：提交修改 PR 至 apache/pulsar，待确认无误后合入 apache/pulsar。

日常工作流程推荐非技术用户使用 GitHub 桌面版进行操作，更加友好易用，让我们来看看吧。

1. branch

1）设置 Current repository 为 <user>/pulsar；

2）点击 Current branch > New branch，打开 Create a branch 对话框。

3）在 Create a branch 对话框：

输入修改分支的名称，例如：wldtest；

指定修改分支基于的分支，默认为 master；

点击 Create branch。

branch 操作完成后，点击 Current branch，从列表中查询并切换至新建分支。

2. edit

打开已下载至本地的工作目录，使用适当的 MarkDown 工具，编辑项目文件。文件修改后，GitHub 桌面版自动识别并显示变更。

3. commit

确认修改无误后，填写变更说明，点击 Commit to <branch name>，提交本轮修改。

注意：提交文件时，需确认提交到正确的修改分支。

4. push

最后点击 push origin，将文件上传到 GitHub 的个人 <user>/pulsar。

5. pull request

点击 Create Pull Request，跳转到 GitHub 的 Web 页面，填写相关内容。

在 Pull Request 页面，细心如你一定注意到系统自动添加了下面这条合并信息，即请求由 <user>/pulsar 的修改分支，合并到 apache/pulsar 的 master 分支。一旦修改内容确认无误，就成功完成本轮贡献了。

现在，你已经成为一名开源项目的 Contributor，给自己一些掌声吧。

在多人团队开发过程中，良好的工作环境和工作流程（项目管理），有利于进行高效协作。付出额外的学习成本，掌握相关工具和流程是非常有必要的。如果这篇文章恰好能够解决你的困惑，让你的学习过程变得容易了一点点，那就太好了。

---

相关文章：

实施：UI国际化的坑，都踩明白了吗 | 技术传播

实施：Word样式协同共享，降低文档开发成本 | 技术传播

实施：同源下发，保证内容一致性 | 技术传播

其他推荐：

企业级信息管理系统初创方案构思 | 技术传播

技术传播是一片蓝海 | 技术传播

访谈：TC无处不在，只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了，你们还有我 | 技术传播

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测：王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

公众号：techcomm / htstory

微信号：bgrichi

邮箱：hash_0813@163.com