HelloX项目github协同开发指南

概述

为了提高协同开发效率，HelloX项目已托管到github站点上。

依据眼下的开发进展，创建了下列几个子项目：

HelloX操作系统内核项目：https://github.com/hellox-project/HelloX_Kernel.git

HelloX操作系统GUI模块项目：https://github.com/hellox-project/HelloX_GUI.git

面向STM32的移植版：https://github.com/hellox-project/HelloX_STM32.git

兴许依据须要，再添加其他相关子项目，全部这些子项目都是HelloX项目的一部分。

本文档对怎样协同开发进行描写叙述，旨在帮助开源开发者顺利搭建起github协作开发环境，共同开发HelloX项目。

Github工作原理简单介绍

严格来说，github是一个站点的名称，真正的版本号管理功能是由git实现的。为了简便，笼统的觉得github就是一个版本号管理系统就OK了。

事实上，github的工作原理非常easy，借用我们日常开发时使用的策略类比，会非常easy理解。比方，如今有一个开发项目，这个开发项目经过长时间积累。已经有了数万行代码。并由一个组织或个人唯一管理（假设多个人同一时候管理。就乱套了）。

你希望对这个项目进行改动或者优化。

这时候，谨慎起见，你不可能直接在原项目上进行改动，而是把原来的项目复制一份，在这个复制项目上进行改动。

改动完毕后，会总结出改动了哪些内容（改动了哪些文件。加入了哪些文件，删除了哪些文件等），然后把改动的内容提交给管理者审核。审核通过后，管理者会逐一合并到原有项目中。

Github自己主动化的实现了这个过程。

原始项目存放在一个固定的位置，并由一个作者允许管理。比方对于HelloX项目的HelloX操作系统内核源码。其固定存放位置是github.com/hellox-project/HelloX_Kernel，当前的管理者是我本人。

假设你希望參与开发，对内核进行改动。那么就须要首先复制一份（github上叫做fork），到你自己的位于github站点的个人空间内。

这时候你就能够随便改动这份copy了。但因为这份拷贝是在网上，无法直接改动，因此你必须把这份copy下载到本地（github叫做clone），然后在本地进行改动。Github（严格来说，是github的本地工具）会监控这个改动过程。把基本的改动内容都记录下来（之所以记录过程，是方便倒回）。本地改动完之后。你告诉github（叫做commit）。已经改动完毕了，github会把改动的内容统一合并到本地代码库中。

注意，这时候你的改动还是停留在本地代码库中，尚未传递到你自己的网上空间内。

假设要把改动内容上传到你自己的github空间，须要运行一个叫做push的操作，把本地commit的改动，推送到你自己的github空间内。

一旦push完毕，改动才同步到你自己的github空间中。

为了把你的改动合并到原始代码中，你必须发起一个pull request，告诉项目管理者，你做了哪些改动，为什么做这些改动。申请项目管理者合并到主流版本号中。

剩下的事情，就是项目管理者的事了。他会考虑这些改动申请，必要时会发起讨论。或者跟你联系，讨论这些改动的必要性。假设终于确定这些改动是有价值的，那么项目管理者会merge到主流版本号中。并记录你的contribution。

好了。通过上面的描写叙述，记住并理解以下的关键词，后面的操作就非常easy了：

Fork，clone，commit。push，merge

HelloX项目github协作开发指南

首先，你必须了解HelloX项目的背景及目标。推断是否与您的背景或者意图能够匹配。以决定是否要投入开发。

这个过程要谨慎细致，一旦决定要投入。那么就须要遵循开源精神，有始有终，当然，您的贡献会被尽量精确的记录下来（HelloX项目的每一个子项目下，都有authors.txt文件，记录了贡献者的主要贡献及个人信息）。

在决定投入开发之后，剩下的事情就非常easy了。以下一步一步的介绍。

第一步：在github上注冊

在github上注冊一下，创建自己的user space。

这个过程不细说。直接登录github.com，点击sign up就可以。

建议选择注冊的username、邮箱、password等信息。万一您成为github上的大牛，一个非常酷的名字会非常重要。

第二步：fork待參与的项目

在github上注冊成功之后，会一直保持登录。

这时候。建议fork一下您希望參与开发的项目，比方您希望參与HelloX项目中的HelloX操作系统STM32版子项目，那么在浏览器地址栏中输入https://github.com/hellox-project。就可以连接到hellox项目的主页下，页面上会列出全部子项目。选择当中的一个。进去之后，点击页面上的forkbutton，就可以复制一份到您自己的空间。

再回到您自己的个人页面。就可以看到fork过来的项目。

第三步：下载并安装githubclient

下列地址能够下载githubclient：

https://help.github.com/articles/set-up-git

下载后，直接运行就可以。

注意，依据我的经验，上面网页上下载的仅仅是一个launch程序。并非真正的github安装程序。这个launch程序会进一步从github站点上（貌似托管在Amazon的云上）下载安装程序。

这个过程会比較长，网络情况不好的话，可能会失败。请多试几次。

在安装过程中。会提示您输入第一步创建的github账户信息。

第四步：启动github命令行client。下载项目

最新的github版本号。提供图形界面和命令行界面。

尽管图形界面做得非常简洁非常好看，但用起来还是感觉不太方便，我个人仍然倾向于github命令行client。

依照缺省安装，github会在桌面上生成一个git shell的图标。双击就可以进入命令行界面。这个命令行界面整合了github的相关命令和windows相关命令，比原来的unix命令行风格好用了非常多。

创建一个本地工作文件夹，比方D:\HelloX。然后使用CD等命令，定位到工作文件夹，运行下列命令：

D:\HelloX>git clone https://github.com/yourname/HelloX_STM32.git

就可以把您在github上fork的项目。下载到本地。注意把上述URL中的username，换成你自己的githubusername。

下载完毕之后。进入新创建的项目文件夹（位于您的工作文件夹下）。然后会发现命令行提示符变了。运行git status命令，就可以看到当前项目的状态。

第五步：对源码进行编辑和改动

这一步是核心工作，使用编译器打开下载的项目。比方用MDK。能够直接打开STM32版的HelloX内核项目。遵循正常的程序编写流程，对源码进行改动就可以。

第六步：提交本地改动

第五步改动完毕之后，您所做的改动仅仅是停留在源码文件里，尚未被github接纳到它自己的数据库中。

这时候。必须在命令行下运行commit操作。

步骤例如以下：

1.      运行git status命令。会列做了改动的文件，包含添加的源码文件、删除的源码文件；

2.      运行git add . 命令（注意命令后面的点号），把改动添加到github管理的数据库中；

3.      运行git commit –m “改动描写叙述” 命令，把改动提交到github本地库中。注意，引號中的描写叙述，是对本次改动的简要介绍，会呈如今源码文件的改动历史中。

完毕上述步骤之后。您所做的改动就记录到github本地库中了。

假设做进一步的源码改动，改动完毕后，反复上述操作，提交到本地库中。

第七步：把本地改动上载到github

在本地代码库上完毕提交之后，改动还是局限在本地库，尚未上传到github的个人空间内。这时候运行下列命令，把改动的代码同步到您自己的github空间中：

D:\HelloX>git push –u origin master

当中的origin，代表代码的原始版本号，即是您自己在github上fork的版本号（注意不是项目的最原始版本号）。Master则是本地版本号。

第八步：发起pullrequest，请求合并改动

Push到个人github空间之后，假设希望合并到项目的主版本号中。必须发起pull request。让项目管理员来审核您所做的改动。并决定是否合并到项目主版本号中。详细操作是。在您自己的github项目页面上。点击pull request，会显示出创建pull request的页面。假设感觉页面内容非常复杂，不要紧，直接点击create pull request就可以，大部分内容。github已帮助您填好了。

到此。您的大部分工作就完毕了，接下来就是项目管理员审核pull request，并讨论是否终于合并到版本号中。

假设确定要合并，那么您的contribution会被记录下来。