作者 谢恩铭 转载请注明出处
公众号「程序员联盟」（微信号：ProgrammerLeague ）
原文：https://www.jianshu.com/p/21af4f24d8db

这篇文章写于 2016 年 8 月 11 日

内容简介

  1. 前言
  2. 前提
  3. 开始实作
  4. 创建错误报告
  5. 提交补丁

1. 前言

之前写了文章 Android开源项目学习 | QKSMS短信App 和 Git，Github和Gitlab简介和基本使用, 今天偶然发现了一个 QKSMS 的问题(Bug)​。

我解决了问题, 并在 QKSMS 的 Github 页面上提交了补丁。

正好借此来聊聊如何在 Github 上为开源项目做贡献, 让你的 Github 成为你的补充简历, 从此升职加薪, 当上总经理, 出任 CEO, 迎娶白富美, 走向人生巅峰, 指日可待啊~

好了, 开个玩笑。还是踏踏实实做人, 好好学习, 天天向上吧!

2. 前提

首先, 你要会用 Git 和 Github。还不了解的, 去看我上面那篇关于 Git 和 Github 的文章。

Github 的页面语言是英语, 如果你英语还不好, 或者正在入门, 请看: 对于程序员, 为什么英语比数学更重要? 如何学习

3. 开始实作

首先, 一个Github上的开源项目, 是有作者的, 有的是个人(例如QKSMS), 有的是团队(例如Google的Sample的Github页面: https://github.com/googlesamples) 。

QKSMS的作者是Moez Bhatti, 他活跃度很高:

QKSMS的页面是:
https://github.com/moezbhatti/qksms

4. 创建错误报告

发现一个Github的开源项目的问题(issue)之后, 我们可以在项目页面点击Issues那个标签栏, 去到Issues页面:

点击New Issue(新问题)的绿色按钮来创建一个新的issue:

编辑你的issue, 点击Submit new issue(提交新问题)来提交你的issue。

我创建的issue:
https://github.com/moezbhatti/qksms/issues/585

如下:

可以看到, issue的文本里, 有几个区块, 以后如果用Redmine, Bugzilla这类的Bug合作平台, 也可以遵照下面的格式来描述一个bug:

  1. DESCRIPTION : 描述。issue的简单描述。我写的是"当在设置的Activity中旋转屏幕, 之后再按回退键, QKSMS奔溃。这个问题同时存在于Google Play上下载的版本和从Github上下载编译的版本。这个问题只发生在进入设置的子类型设置(例如: 外观, 通用, 通知, MMS, QK Reply, 等等)中时"。
  2. STEPS : 重现issue的步骤。依顺序写下如何重现问题的步骤。
  3. EXPECTED : 期待的表现。也就是你期待的正确表现是什么。
  4. OBSERVATIONS : 实际的表现。也就是你观察到的错误表现。

我还附上了Android Studio中复制过来的Logcat的奔溃报告。在Logcat from Android Studio那个区块。

5. 提交补丁

你在代码中做了修改, 测试你的修改没问题了之后, 就可以向Github提交你的补丁啦~

在Git中如何制作补丁呢?

非常简单。用

git format-patch

命令即可。

首先你在Git中提交你的修改

git add QKSMS/src/main/java/com/moez/QKSMS/ui/settings/SettingsActivity.java
git commit -m "Fix crash when backPress from SettingsActivity after Orientation changed"

然后, 用git log来查看你刚提交的commit和之前的一个commit:

git log

可以看到, 我们刚才提交的commit, 其hash值是c0c949a4a0812e27f1102e566e8c11fe82b29dc5, 而前一个commit的hash值是d50befdf6377ff42d2307ddd59628f0490c3eb86

根据

man git-format-patch

显示的文档所说, git format-patch 后接你的改动从哪里开始的那个commit的hash值, 因为我们的改动是基于前一个commit(hash值为d50befdf6377ff42d2307ddd59628f0490c3eb86), 因此, 要生成patch补丁, 只需:

git format-patch d50befdf6377ff42d2307ddd59628f0490c3eb86

可以看到, 它为我们生成了补丁文件:

0001-Fix-crash-when-backPress-from-SettingsActivity-after.patch

就在当前目录里:

补丁的改动如下:

可以用

git show

来查看

补丁在这里

直接在错误报告里提交补丁

如果你对代码的改动很少, 那么可以考虑制作patch(补丁)文件, 然后直接用评论附件形式上传到你刚才创建的错误报告中:

在下面所示的方框中(Leave a comment)编辑你的comment(评论), 你随时可以预览你的评论, 点击Preview(预览)即可, 要回到编辑模式, 点击Write(写)。

然后看到有一段文字: Attach files by dragging & dropping or select them.

意思是: 你可以拖动文件到这个编辑框来附上你的文件, 或者也可以点击"select them"来手动选择文件。

不管你用哪种方式, 把文件附上之后(我这里的补丁文件名是0001-Fix-crash-when-backPress-from-SettingsActivity-after.patch.txt ), 点击绿色的Comment按钮, 评论就被提交了, 文件如下图中红框所示。

我在评论里说: "我创建了一个补丁, 修正了这个问题, 而且也同时修正了一个小问题, 就是在设置页面的子类型页面中, 如果旋转屏幕, 会自动回到设置页面的主页面。不过您也许会想到更好的解决方案。"

PS: 因为Github不能提交patch结尾的文件, 所以我把补丁文件改成了以.txt结尾, 但并不妨碍打补丁。

在Git中如何打补丁呢?

非常简单:

  1. cd到项目根目录下
  2. 用git apply命令, 后接补丁文件的路径
  3. git add 修改的文件
  4. git commit
  5. git push

实际操作:

cd ~/qksms
git apply ~/Desktop/0001-Fix-crash-when-backPress-from-SettingsActivity-after.patch.txt
git add QKSMS/src/main/java/com/moez/QKSMS/ui/settings/SettingsActivity.java
git commit -m "随便你写什么"
git push origin master   # 或者提交到其他分支

创建新的分支来提交补丁

如果你的改动比较多, 你就不能在错误报告的评论里附上一个小小补丁文件就了事了, 最好用创建分支的方式来提交你的pull request(提交请求)。

如果你是Github的开源项目的作者本人或者是被作者指定的贡献者, 你可以直接git push你的branch到项目代码仓库, 然后可以直接创建pull request。

点击Pull requests标签, 进入Pull requests页面:

点击上图中 New pull request

然后选择你提交的分支和你要合并的目标分支。

但是, 一般我们都是游客, 没有权限git push到开源项目的代码仓库。

所以需要用另一种方式来提交补丁, 可以称之为 pull request by comparing across forks (通过对比交叉复刻来提交请求)。

首先, 我们需要fork(复刻)这个开源项目, 点击下图中的fork按钮:

稍等片刻, 开源项目就被复刻到你的个人Github目录了, 如下:

可以看到, 现在我自己的Github仓库已经有了这个开源项目的代码, 不过标明了 "forked from moezbhatti/qksms", 就是说这个仓库不是我自己的, 是从moezbhatti/qksms项目复刻过来的。

接着, 你用git clone来把复刻的项目拉取到本地:

首先, 点击上图中 Clone or download按钮, 复制那个链接: https://github.com/frogoscar/qksms.git

然后在终端里输入:

mkdir github
cd github
git clone https://github.com/frogoscar/qksms.git
cd qksms

你可以先git checkout -b来基于master分支创建一个你自己的分支(名字随便取), 直接改动代码, 然后修改代码, 假如你的补丁, 再git add, git commit, git push。

git checkout -b enmingxie/Fix_crash_when_backPress_from_SettingsActivity_after_Orientation_changed

因为我之前已经从其他地方创建了补丁, 因此, 我就不手动改代码了, 直接用git apply来打补丁。

git apply ~/Desktop/0001-Fix-crash-when-backPress-from-SettingsActivity-after.patch

通过git status命令(上图中看到的git st是我自己配置的alias), 我们可以看到QKSMS/src/main/java/com/moez/QKSMS/ui/settings/SettingsActivity.java文件被改变了,还没有git add, 因此:

git add QKSMS/src/main/java/com/moez/QKSMS/ui/settings/SettingsActivity.java
git commit -m "Fix crash when backPress from SettingsActivity after Orientation changed"
git push origin enmingxie/Fix_crash_when_backPress_from_SettingsActivity_after_Orientation_changed

输入你的github用户名和密码(如果你配置了SSH, 则不必输入)。

再到Github的项目页面, 点击F5刷新, 可以看到刚push的enmingxie/Fix_crash_when_backPress_from_SettingsActivity_after_Orientation_changed这个branch(分支)已经有了。

此时, 再去开源项目页面, 首先:

  • base fork那里, moezbhatti/qksms是QKSMS的代码仓库。
  • base那里, master表示是QKSMS的master分支(主分支)。

选择对应分支:

  • head fork那里, frogoscar/qksms是我的Github上的复刻的QKSMS的代码仓库。
  • compare那里, enmingxie/Fix_crash_when_backPress_from_SettingsActivity_after_Orientation_changed是我刚push的分支。

可以看到我的分支与开源项目(QKSMS)主分支(master)的(diff)改动了:

然后点击 Create pull request (生成提交请求), 编辑提交请求的文本, 再点击Submit pull request, 就完工啦!

这样, 作者审核你的分支之后, 就可以决定是否使用你的补丁啦!

恭喜你! 第一个提交的Github补丁! 加油吧~

我是谢恩铭，在巴黎奋斗的软件工程师。
热爱生活，喜欢游泳，略懂烹饪。
人生格言：「向着标杆直跑」