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

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

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

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

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

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

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

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

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

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

修改代碼

檢查改動

將改動提交到分支中

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

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

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

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

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

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

利用合并請求

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

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

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

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

Figure 6-15. 最終的合并請求

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

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

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

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

不必總是 Fork

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

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

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

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

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

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

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

與上游保持同步

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

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

參考

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

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

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

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

Figure?6-22 這樣。

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

圖片

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