6.2 對項目做出貢獻

對項目做出貢獻

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

派生（Fork）項目

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

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

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

你可以通過點擊項目頁面右上角的“Fork”按鈕，來派生這個項目。

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

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

修改代碼

檢查改動

將改動提交到分支中

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

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

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

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

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

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

利用合并請求

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

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

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

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

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

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

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

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

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

不必總是 Fork

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

合并請求的進階用法

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

將合并請求制作成補丁

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

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

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

與上游保持同步

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

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

參考

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

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

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

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

Figure?6-22 這樣。

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

圖片

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