對(duì)項(xiàng)目做出貢獻(xiàn)

賬戶已經(jīng)建立好了，現(xiàn)在我們來了解一些能幫助你對(duì)現(xiàn)有的項(xiàng)目做出貢獻(xiàn)的知識(shí)。

派生（Fork）項(xiàng)目

如果你想要參與某個(gè)項(xiàng)目，但是并沒有推送權(quán)限，這時(shí)可以對(duì)這個(gè)項(xiàng)目進(jìn)行“派生”。派生的意思是指，GitHub 將在你的空間中創(chuàng)建一個(gè)完全屬于你的項(xiàng)目副本，且你對(duì)其具有推送權(quán)限。

在以前，“fork”是一個(gè)貶義詞，指的是某個(gè)人使開源項(xiàng)目向不同的方向發(fā)展，或者創(chuàng)建一個(gè)競(jìng)爭(zhēng)項(xiàng)目，使得原項(xiàng)目的貢獻(xiàn)者分裂。在 GitHub，“fork”指的是你自己的空間中創(chuàng)建的項(xiàng)目副本，這個(gè)副本允許你以一種更開放的方式對(duì)其進(jìn)行修改。

通過這種方式，項(xiàng)目的管理者不再需要忙著把用戶添加到貢獻(xiàn)者列表并給予他們推送權(quán)限。人們可以派生這個(gè)項(xiàng)目，將修改推送到派生出的項(xiàng)目副本中，并通過創(chuàng)建合并請(qǐng)求（Pull Request）來讓他們的改動(dòng)進(jìn)入源版本庫，下文我們會(huì)詳細(xì)說明。創(chuàng)建了合并請(qǐng)求后，就會(huì)開啟一個(gè)可供審查代碼的板塊，項(xiàng)目的擁有者和貢獻(xiàn)者可以在此討論相關(guān)修改，直到項(xiàng)目擁有者對(duì)其感到滿意，并且認(rèn)為這些修改可以被合并到版本庫。

你可以通過點(diǎn)擊項(xiàng)目頁面右上角的“Fork”按鈕，來派生這個(gè)項(xiàng)目。

將派生出的副本克隆到本地

創(chuàng)建出名稱有意義的分支

修改代碼

檢查改動(dòng)

將改動(dòng)提交到分支中

將新分支推送到 GitHub 的副本中

現(xiàn)在到 GitHub 上查看之前的項(xiàng)目副本，可以看到 GitHub 提示我們有新的分支，并且顯示了一個(gè)大大的綠色按鈕讓我們可以檢查我們的改動(dòng)，并給源項(xiàng)目創(chuàng)建合并請(qǐng)求。

你也可以到“Branches”（分支）頁面查看分支并創(chuàng)建合并請(qǐng)求： https://github.com/<用戶名>/<項(xiàng)目名>/branches

Figure 6-11. 合并請(qǐng)求創(chuàng)建頁面

當(dāng)你單擊了“Create pull request”（創(chuàng)建合并請(qǐng)求）的按鈕后，這個(gè)項(xiàng)目的擁有者將會(huì)收到一條包含關(guān)改動(dòng)和合并請(qǐng)求頁面的鏈接的提醒。

雖然合并請(qǐng)求通常是在貢獻(xiàn)者準(zhǔn)備好在公開項(xiàng)目中提交改動(dòng)的時(shí)候提交，但是也常被用在仍處于開發(fā)階段的內(nèi)部項(xiàng)目中。因?yàn)楹喜⒄?qǐng)求在提交后 依然可以加入新的改動(dòng) ，它也經(jīng)常被用來建立團(tuán)隊(duì)合作的環(huán)境，而不只是在最終階段使用。

利用合并請(qǐng)求

現(xiàn)在，項(xiàng)目的擁有者可以看到你的改動(dòng)并合并它，拒絕它或是發(fā)表評(píng)論。在這里我們就當(dāng)作他喜歡這個(gè)點(diǎn)子，但是他想要讓燈熄滅的時(shí)間比點(diǎn)亮的時(shí)間稍長(zhǎng)一些。

接下來可能會(huì)通過電子郵件進(jìn)行互動(dòng)，就像我們?cè)?Chapter?5 中提到的工作流程那樣，但是在 GitHub，這些都在線上完成。項(xiàng)目的擁有者可以審查修改，只需要單擊某一行，就可以對(duì)其發(fā)表評(píng)論。

Figure 6-13. 通過電子郵件發(fā)送的評(píng)論提醒

每個(gè)人都能在合并請(qǐng)求中發(fā)表評(píng)論。在 Figure?6-14 里我們可以看到項(xiàng)目擁有者對(duì)某行代碼發(fā)表評(píng)論，并在討論區(qū)留下了一個(gè)普通評(píng)論。你可以看到被評(píng)論的代碼也會(huì)在互動(dòng)中顯示出來。

Figure 6-15. 最終的合并請(qǐng)求

如果你點(diǎn)開合并請(qǐng)求的“Files Changed”（更改的文件）選項(xiàng)卡，你將會(huì)看到“整理過的”差異表 —— 也就是這個(gè)分支被合并到主分支之后將會(huì)產(chǎn)生的所有改動(dòng)，其實(shí)就是 git diff master...<分支名> 命令的執(zhí)行結(jié)果。你可以瀏覽 “確定引入了哪些東西” 來了解更多關(guān)于差異表的知識(shí)。

你還會(huì)注意到，GitHub 會(huì)檢查你的合并請(qǐng)求是否能直接合并，如果可以，將會(huì)提供一個(gè)按鈕來進(jìn)行合并操作。這個(gè)按鈕只在你對(duì)版本庫有寫入權(quán)限并且可以進(jìn)行簡(jiǎn)潔合并時(shí)才會(huì)顯示。你點(diǎn)擊后 GitHub 將做出一個(gè)“非快進(jìn)式”（non-fast-forward）合并，即使這個(gè)合并 能夠 快進(jìn)式（fast-forward）合并，GitHub 依然會(huì)創(chuàng)建一個(gè)合并提交。

如果你需要，你還可以將分支拉取并在本地合并。如果你將這個(gè)分支合并到 master 分支中并推送到 GitHub，這個(gè)合并請(qǐng)求會(huì)被自動(dòng)關(guān)閉。

這就是大部分 GitHub 項(xiàng)目使用的工作流程。創(chuàng)建分支，基于分支創(chuàng)建合并請(qǐng)求，進(jìn)行討論，根據(jù)需要繼續(xù)在分支上進(jìn)行修改，最終關(guān)閉或合并合并請(qǐng)求。

不必總是 Fork

有件很重要的事情：你可以在同一個(gè)版本庫中不同的分支提交合并請(qǐng)求。如果你正在和某人實(shí)現(xiàn)某個(gè)功能，而且你對(duì)項(xiàng)目有寫權(quán)限，你可以推送分支到版本庫，并在 master 分支提交一個(gè)合并請(qǐng)求并在此進(jìn)行代碼審查和討論的操作。不需要進(jìn)行“Fork”。

合并請(qǐng)求的進(jìn)階用法

目前，我們學(xué)到了如何在 GitHub 平臺(tái)對(duì)一個(gè)項(xiàng)目進(jìn)行最基礎(chǔ)的貢獻(xiàn)?，F(xiàn)在我們會(huì)教給你一些小技巧，讓你可以更加有效率地使用合并請(qǐng)求。

將合并請(qǐng)求制作成補(bǔ)丁

有一件重要的事情：許多項(xiàng)目并不認(rèn)為合并請(qǐng)求可以作為補(bǔ)丁，就和通過郵件列表工作的的項(xiàng)目對(duì)補(bǔ)丁貢獻(xiàn)的看法一樣。大多數(shù)的 GitHub 項(xiàng)目將合并請(qǐng)求的分支當(dāng)作對(duì)改動(dòng)的交流方式，并將變更集合起來統(tǒng)一進(jìn)行合并。

這是個(gè)重要的差異，因?yàn)橐话銇碚f改動(dòng)會(huì)在代碼完成前提出，這和基于郵件列表的補(bǔ)丁貢獻(xiàn)有著天差地別。這使得維護(hù)者們可以更早的溝通，由社區(qū)中的力量能提出更好的方案。當(dāng)有人從合并請(qǐng)求提交了一些代碼，并且維護(hù)者和社區(qū)提出了一些意見，這個(gè)補(bǔ)丁系列并不需要從頭來過，只需要將改動(dòng)重新提交并推送到分支中，這使得討論的背景和過程可以齊頭并進(jìn)。

舉個(gè)例子，你可以回去看看 Figure?6-15，你會(huì)注意到貢獻(xiàn)者沒有變基他的提交再提交一個(gè)新的合并請(qǐng)求，而是直接增加了新的提交并推送到已有的分支中。如果你之后再回去查看這個(gè)合并請(qǐng)求，你可以輕松地找到這個(gè)修改的原因。點(diǎn)擊網(wǎng)頁上的“Merge”（合并）按鈕后，會(huì)建立一個(gè)合并提交并指向這個(gè)合并請(qǐng)求，你就可以很輕松的研究原來的討論內(nèi)容。

與上游保持同步

如果你的合并請(qǐng)求由于過時(shí)或其他原因不能干凈地合并，你需要進(jìn)行修復(fù)才能讓維護(hù)者對(duì)其進(jìn)行合并。GitHub 會(huì)對(duì)每個(gè)提交進(jìn)行測(cè)試，讓你知道你的合并請(qǐng)求能否簡(jiǎn)潔的合并。

“變基的風(fēng)險(xiǎn)” 中提到的問題。相對(duì)的，將變基后的分支推送到 GitHub 上的一個(gè)新分支中，并且創(chuàng)建一個(gè)全新的合并請(qǐng)求引用舊的合并請(qǐng)求，然后關(guān)閉舊的合并請(qǐng)求。

參考

你的下個(gè)問題可能是“我該如何引用舊的合并請(qǐng)求？”。有許多方法可以讓你在 GitHub 上的幾乎任何地方引用其他東西。

先從如何對(duì)合并請(qǐng)求或議題（Issue）進(jìn)行相互引用開始。所有的合并請(qǐng)求和議題在項(xiàng)目中都會(huì)有一個(gè)獨(dú)一無二的編號(hào)。舉個(gè)例子，你無法同時(shí)擁有 3 號(hào)合并請(qǐng)求和 3 號(hào)議題。如果你想要引用任何一個(gè)合并請(qǐng)求或議題，你只需要在提交或描述中輸入 #<編號(hào)> 即可。你也可以指定引用其他版本庫的議題或合并請(qǐng)求，如果你想要引用其他人對(duì)該版本庫的“Fork”中的議題或合并請(qǐng)求，輸入 用戶名#<編號(hào)> ，如果在不同的版本庫中，輸入 用戶名/版本庫名#<編號(hào)> 。

我們來看一個(gè)例子。假設(shè)我們對(duì)上個(gè)例子中的分支進(jìn)行了變基，并為此創(chuàng)建一個(gè)新的合并請(qǐng)求，現(xiàn)在我們希望能在新的合并請(qǐng)求中引用舊的合并請(qǐng)求。我們同時(shí)希望引用一個(gè)派生出的項(xiàng)目中的議題和一個(gè)完全不同的項(xiàng)目中的議題，就可以像 Figure?6-18 這樣填寫描述。

Figure?6-20 中展示的那樣。

Figure?6-22 這樣。

如果加入語言的名稱，就像我們這里加入的“java”一樣，GitHub 會(huì)自動(dòng)嘗試對(duì)摘錄的片段進(jìn)行語法高亮。在下面的例子中，它最終會(huì)渲染成這個(gè)樣子： Figure?6-24 。

圖片

從技術(shù)層面來說，這并不是 GitHub 風(fēng)格 Markdown 的功能，但是也很有用。如果不想使用 Markdown 語法來插入圖片，GitHub 允許你通過拖拽圖片到文本區(qū)來插入圖片。