实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

iFangcy_
329 阅读7分钟
原文链接： mp.weixin.qq.com

前段时间有幸参与了开源社区的活动，并且借由 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 mastergit fetch upstreamgit rebase upstream/mastergit 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，给自己一些掌声吧。 六、总结 在多人团队开发过程中，良好的工作环境和工作流程（项目管理），有利于进行高效协作。付出额外的学习成本，掌握相关工具和流程是非常有必要的。如果这篇文章恰好能够解决你的困惑，让你的学习过程变得容易了一点点，那就太好了。
作者：睿齐 技术传播从业者/品牌内容策划 自由摄影师/自由撰稿人
avatar
文章
阅读
粉丝