Tianchi项目(天池Qt共享库项目,参见
关于《天池共享源码库》,
最新版本v0.0.2的功能列表请看)现已正式启动,程序放在github上面,地址是
https://github.com/qtcn/tianchi,希望参与
开发和维护的人员(包括开发、文档、测试等)并具有提交权限(即可处理Pull Requests提交上来的merge和patch),请首先到下面网址报名(是否具有提交权限,会根据实际参与情况进行处理):
http://www.qtcn.org/bbs/read-htm-tid-52866.html 当然,对于非经常性参与项目或者不熟悉git和github的朋友,也可以通过发邮件(
qtcn_tianchi@groups.163.com)或者直接在项目讨论区(
http://www.qtcn.org/bbs/thread-htm-fid-105.html)发帖来贡献代码,项目维护人员会将其加入到github中。
对于项目代码中的其它要求,请查看项目doc目录下的内容,有任何
问题请发邮件到
qtcn_tianchi@groups.163.com。
已报名tianchi项目开发的朋友们,请查看
QTCN 天池项目版块的帖子内容,以了解如何参与项目开发,根据自己的情况,参与具体的工作内容(后面会说明),提交到github.com上即可,有问题需要沟通探讨的,请在skype讨论组、qtcn.org管理组QQ群里讨论(QQ、skype在报名时会添加),或者直接发邮件讨论也可以(邮件列表名单在报名时会告知),或者在
QTCN 天池项目版块中发帖子讨论。
暂订当前工作内容为以下各项:
1. Tianchi库标准的制定。(由核心成员负责)
2. 合并代码到Tianchi正式库中。(由核心成员负责)
3. 编写Tianchi的演示(测试)程序。
4. 在不同环境下的
编译,和可用性, 对演示程序进行测试。
5. 编写使用文档(直接以doxygen支持的格式写在代码中)。
6. 对代码进行走读,提出BUG或改进建议等。
7. 搜集功能需求和用户反馈(张帖到论坛Tianchi版块)
8. 搜集现有代码,必要时联络作者,确认能否合并入 Tianchi.
9. 改写网上不兼容的代码,注意需要注明出处。收集时尽可能发通知告知作者。
10. 整理发言稿或其它与软件技术无关的资料等。
11. 推广和宣传工作。
开始工作前,请然后仔细阅读下面的关于git和github的使用帮助内容:
1.
Set Up Git注:该步骤所有开发人员适用。如果采用ssh key方式使用github repo,则请阅读下面的链接
Generating SSH Keys 2.
Create A Repo注:参与开发Tianchi项目,则不需要该步
3.
Fork A Repo注:该步骤所有开发人员适用。
4.
Using Pull Requests注:该步骤所有开发人员适用。(向fork repo)提交贡献,有两种方式,一种是直接修改代码申请合并,另一种是生成patch。
5.
Merging a pull request注:具有qtcn/tianchi库的提交权限的人员适用该步骤。这里需要根据用户所提交的pull request的内容然后在线或者本地合并代码并提交(如果用户提交的是patch文件,则只需要打补丁提交)
下面,我们列出Mort网友的一篇文章,以供大家学习参考github的使用:
http://www.soimort.org/posts/149/ Pull Request的正确打开方式(如何在GitHub上贡献开源项目) 27 Mar 2013, by
MortGitHub的官方帮助如下:
发现这个官方文档写得比较简单,并
没有提到开源项目协作方式的一些必要的trick(比如建立topic branch),还有Pull Request的运作细节也没有提到。写个简单的总结补充一下。
Step 1: Fork原项目 这个不解释了,单击一下鼠标就能做到的事情。参见GitHub帮助的
原文。
记得用git remote add添加上游远程库的地址,否则无法追踪上游库的更新。
Step 2: 创建你的主题(topic)branch 这一步
非常重要。GitHub的帮助里没有提到创建主题branch的必要性,你当然可以直接在原项目的默认branch(如master)上进行工作,但实际上:
如果打算为原项目作贡献,强烈建议你为每个主题创建一个单独的branch。举例:如果需要修复原项目的一个和Unicode相关的issue:
$ git branch fix-unicode-error$ git checkout fix-unicode-error
然后在自己的主题branch(这里是fix-unicode-error)下进行工作。
Step 3: 在主题branch下完成需要的工作 记得push相应的主题branch到GitHub。
*(针对贡献者)rebase还是merge? 从实用的角度来讲,
- 当你在主题branch下工作,想要导入来自上游库的(与你当前的工作不冲突的情况下)更新时,使用git rebase。
例如,(假设上游branch为upstream/master)
$ git rebase upstream/master fix-unicode-error
或者直接(如果当前branch已经是fix-unicode-error):
$ git rebase upstream/master
这将把当前branch的开发“base(基础)”推进到一个新的起点,而不会引入多余的commits。
- 当你在某个branch下工作时,git merge可以用来合并来自其他branch的更新。
如果merge的branch来自远程库,一次merge操作会增加一个额外的commit(“Merge branch 'master' ofsomething”)。如果在一个需要发送Pull Request的主题branch下面进行这种操作,(我个人觉得)这不是一种干净的手段。
当你在主线branch(例如master)下进行开发时,git merge可以用来吸收
其他开发branch引入的新特性(包括主项目维护者用来直接merge Pull Requests),很恰当。
Step 4: 发送第一个Pull Request GitHub的
界面:左边选择base branch,右边选择head branch。
base branch:相当于target branch,你希望Pull Request被merge到上游项目的哪个branch里。为什么要叫base branch:base可以理解为你在进行git rebase操作时的那个“base”,也就是你的主题branch所基于的开发base(基础)。
head branch:相当于source branch,你希望自己开发库里的哪个branch被用来进行Pull Request(当然也就是你的主题branch)。
- 为什么要叫head branch:参见下面关于head的定义。
注意head与HEAD(大写)的区别:
head:简单地理解,就是指向某个commit对象的一个reference。它可以是一个branch的名称(例如,默认的master),也可以是一个tag的名称。一个库可以同时有任意多个head。
HEAD:当前活动的head。在任意时刻,存在且仅存在一个HEAD。它可以是指向当前branch的head(比如,指向master,假如master是当前branch的话);也可以不指向任何特定的branch(这叫做detached HEAD)。
系统会从你选择的head branch(在这里,是主题branch)的这个head开始匹配所有不包含在base branch中的commits,然后自动视作你的主题branch相对于base所增加的新特性,放进同一个Pull Request中提交。
Step 5: Pull Request发送之后…… 一旦你从自己的主题branch(例如fix-unicode-error)推送了一条Pull Request,那么在这条PullRequest被关闭之前,再次向这个branch里push代码,所有的commits都会被自动追加到这个PullRequest后面(不需要再另开Pull Request)。
这个功能尤其有用,比如你最初提交的Pull Request里存在某些问题,项目维护者要求你打回去修改;或者要求你给你的新feature添加一条相应的unit test(这种情况简直太常见了)。只要追加commits到你的这个主题branch中即可。
(题外话:如果原项目有Travis CI,那么它也会在每次追加push之后对Pull Request重新
执行一遍测试)
*(针对项目维护者)cherry-pick、format-patch和am 这几条命令主要针对项目的维护者,稍微提一下。
git pull和git merge是GitHub上最常用的merge Pull Requests的方式,在命令行下merge之后,GitHub上面的Pull Request也会相应地自动关闭。
如果贡献者一次提交了多条commits,有些是维护者并不想要的,可以用这几条命令来选择性地手动commit。(这也适用于某些项目不是借助于GitHub的Pull Request,而是通过邮件列表和patch文件来进行协作开发的情形)
在这种情况下,GitHub上面的Pull Request并不能自动关闭,需要维护者手工操作。
Step 6: Pull Request关闭之后 如果是已经被merge后关闭的Pull Request,你可以在页面的最下方找到一个“
Delete this branch”的蓝色
按钮。
这表明这个主题branch的历史使命已经完成(fix-unicode-error的commit已经被合并到主项目中),可以安全地从远程库中删除了。
在本地库中亦可删除这个branch:
$ git branch -d fix-unicode-error
反之,如果你的主题branch并没有被merge就被维护者关掉的话,你还可以继续再拿它来开新的Pull Request
去骚扰主项目(´▽` )。
总结 在哪些情况下
可以直接使用master branch来提交Pull Request:
- 你只想为主项目贡献某一处代码,贡献完自己的repo就可以扔的那种。
- 你打算为主项目长期贡献代码,而且希望追随原项目的主线开发,不保留自己的特性。
- 你打算为主项目长期贡献代码,默认master branch追随原项目主线,把自己的特性放到别的branch中。
在哪种情况下
应该使用主题branch来提交Pull Request:
- 想用master branch完全来做自己的开发。在这种情形下:会从上游库合并更新,但是这些merge本身的commits显然不可能作为返还到上游库的Pull Request的一部分。
- 存在自己的(未被merge或者不想被merge到上游库的)commits。
鉴于Git的分布式开发哲学,每一个库均可以看作是一个独立的项目,显然是后一种(为每一个新特性建立一个专门的主题branch来向主项目推送Pull Request)的贡献方式更可取。
解释完毕(`・ω・´)