作者 謝恩銘，公眾號「程序員聯(lián)盟」（微信號：coderhub）。
轉載請注明出處。
原文：http://www.itdecent.cn/p/21af4f24d8db
這篇文章寫于 2016 年 8 月 11 日
內容簡介
- 前言
- 前提
- 開始實作
- 創(chuàng)建錯誤報告
- 提交補丁
1. 前言
之前寫了文章 Android開源項目學習 | QKSMS短信App 和 Git，Github和Gitlab簡介和基本使用, 今天偶然發(fā)現(xiàn)了一個 QKSMS 的問題(Bug)?。
我解決了問題, 并在 QKSMS 的 Github 頁面上提交了補丁。
正好借此來聊聊如何在 Github 上為開源項目做貢獻, 讓你的 Github 成為你的補充簡歷, 從此升職加薪, 當上總經(jīng)理, 出任 CEO, 迎娶白富美, 走向人生巔峰, 指日可待啊~
好了, 開個玩笑。還是踏踏實實做人, 好好學習, 天天向上吧!
2. 前提
首先, 你要會用 Git 和 Github。還不了解的, 去看我上面那篇關于 Git 和 Github 的文章。
Github 的頁面語言是英語, 如果你英語還不好, 或者正在入門, 請看: 對于程序員, 為什么英語比數(shù)學更重要? 如何學習
3. 開始實作
首先, 一個Github上的開源項目, 是有作者的, 有的是個人(例如QKSMS), 有的是團隊(例如Google的Sample的Github頁面: https://github.com/googlesamples) 。
QKSMS的作者是Moez Bhatti, 他活躍度很高:
QKSMS的頁面是:
https://github.com/moezbhatti/qksms
4. 創(chuàng)建錯誤報告
發(fā)現(xiàn)一個Github的開源項目的問題(issue)之后, 我們可以在項目頁面點擊Issues那個標簽欄, 去到Issues頁面:
點擊New Issue(新問題)的綠色按鈕來創(chuàng)建一個新的issue:
編輯你的issue, 點擊Submit new issue(提交新問題)來提交你的issue。
我創(chuàng)建的issue:
https://github.com/moezbhatti/qksms/issues/585
如下:
可以看到, issue的文本里, 有幾個區(qū)塊, 以后如果用Redmine, Bugzilla這類的Bug合作平臺, 也可以遵照下面的格式來描述一個bug:
- DESCRIPTION : 描述。issue的簡單描述。我寫的是"當在設置的Activity中旋轉屏幕, 之后再按回退鍵, QKSMS奔潰。這個問題同時存在于Google Play上下載的版本和從Github上下載編譯的版本。這個問題只發(fā)生在進入設置的子類型設置(例如: 外觀, 通用, 通知, MMS, QK Reply, 等等)中時"。
- STEPS : 重現(xiàn)issue的步驟。依順序寫下如何重現(xiàn)問題的步驟。
- EXPECTED : 期待的表現(xiàn)。也就是你期待的正確表現(xiàn)是什么。
- OBSERVATIONS : 實際的表現(xiàn)。也就是你觀察到的錯誤表現(xiàn)。
我還附上了Android Studio中復制過來的Logcat的奔潰報告。在Logcat from Android Studio那個區(qū)塊。
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
根據(jù)
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(補丁)文件, 然后直接用評論附件形式上傳到你剛才創(chuàng)建的錯誤報告中:
在下面所示的方框中(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按鈕, 評論就被提交了, 文件如下圖中紅框所示。
我在評論里說: "我創(chuàng)建了一個補丁, 修正了這個問題, 而且也同時修正了一個小問題, 就是在設置頁面的子類型頁面中, 如果旋轉屏幕, 會自動回到設置頁面的主頁面。不過您也許會想到更好的解決方案。"
PS: 因為Github不能提交patch結尾的文件, 所以我把補丁文件改成了以.txt結尾, 但并不妨礙打補丁。
在Git中如何打補丁呢?
非常簡單:
- cd到項目根目錄下
- 用git apply命令, 后接補丁文件的路徑
- git add 修改的文件
- git commit
- 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 # 或者提交到其他分支
創(chuàng)建新的分支來提交補丁
如果你的改動比較多, 你就不能在錯誤報告的評論里附上一個小小補丁文件就了事了, 最好用創(chuàng)建分支的方式來提交你的pull request(提交請求)。
如果你是Github的開源項目的作者本人或者是被作者指定的貢獻者, 你可以直接git push你的branch到項目代碼倉庫, 然后可以直接創(chuàng)建pull request。
點擊Pull requests標簽, 進入Pull requests頁面:
點擊上圖中 New pull request
然后選擇你提交的分支和你要合并的目標分支。
但是, 一般我們都是游客, 沒有權限git push到開源項目的代碼倉庫。
所以需要用另一種方式來提交補丁, 可以稱之為 pull request by comparing across forks (通過對比交叉復刻來提交請求)。
首先, 我們需要fork(復刻)這個開源項目, 點擊下圖中的fork按鈕:
稍等片刻, 開源項目就被復刻到你的個人Github目錄了, 如下:
可以看到, 現(xiàn)在我自己的Github倉庫已經(jīng)有了這個開源項目的代碼, 不過標明了 "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分支創(chuàng)建一個你自己的分支(名字隨便取), 直接改動代碼, 然后修改代碼, 假如你的補丁, 再git add, git commit, git push。
git checkout -b enmingxie/Fix_crash_when_backPress_from_SettingsActivity_after_Orientation_changed
因為我之前已經(jīng)從其他地方創(chuàng)建了補丁, 因此, 我就不手動改代碼了, 直接用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(分支)已經(jīng)有了。
此時, 再去開源項目頁面, 首先:
- 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補丁! 加油吧~
我是 謝恩銘，公眾號「程序員聯(lián)盟」（微信號：coderhub）運營者，慕課網(wǎng)精英講師 Oscar 老師，終生學習者。
熱愛生活，喜歡游泳，略懂烹飪。
人生格言：「向著標桿直跑」
