实施:GitHub + MarkDown 文档系统的工作环境部署及工作流程说明

前段时间有幸参与了开源社区的活动,并且借由 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,给自己一些掌声吧。

六、总结

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

作者:睿齐

技术传播从业者/品牌内容策划

自由摄影师/自由撰稿人

我来评几句
登录后评论

已发表评论数()

相关站点

+订阅
热门文章