一、派生項目

• 如果想要參與某個項目，但是并沒有推送權限，這時可以對這個項目進行“派生（Fork）”。當“派生”一個項目時，GitHub 會在我們的空間中創建一個完全屬于自己的項目副本，且對其具有推送權限。
• 在以前，“fork”是一個貶義詞，指的是某個人使開源項目向不同的方向發展，或者創建一個競爭項目，使得原項目的貢獻者分裂。在 GitHub，“fork”指的是自己的空間中創建的項目副本，這個副本允許以一種更開放的方式對其進行修改。
• 通過這種方式，項目的管理者不再需要忙著把用戶添加到貢獻者列表并給予他們推送權限。人們可以派生這個項目，將修改推送到派生出的項目副本中，并通過創建拉取請求（Pull Request，簡稱 PR）來讓他們的改動進入源版本庫。創建了拉取請求后，就會開啟一個可供審查代碼的板塊，項目的擁有者和貢獻者可以在此討論相關修改，直到項目擁有者對其感到滿意，并且認為這些修改可以被合并到版本庫。
• 可以通過點擊項目頁面右上角的“Fork”按鈕，來派生這個項目：

• 稍等片刻，將被轉到新項目頁面，該項目包含可寫的代碼副本。

二、GitHub 流程

• GitHub 設計了一個以拉取請求為中心的特殊合作流程，它基于我們在主題分支的 Git分支中提到的工作流程，不管是在一個緊密的團隊中使用單獨的版本庫，或者使用許多的“Fork”來為一個由陌生人組成的國際企業或網絡做出貢獻，這種合作流程都能應付。
• 流程通常如下：
• • 派生一個項目；
• • 從 master 分支創建一個新分支；
• • 提交一些修改來改進項目；
• • 將這個分支推送到 GitHub 上；
• • 創建一個拉取請求；
• • 討論，根據實際情況繼續修改；
• • 項目的擁有者合并或關閉你的拉取請求；
• • 將更新后的 master 分支同步到你的派生中。
• 這基本和 Git之深入解析如何使用Git的分布式工作流程與如何管理多人開發貢獻的項目中的集成管理者工作流的一體化管理流程差不多，但是團隊可以使用 GitHub 提供的網頁工具替代電子郵件來交流和審查修改。

① 創建拉取請求

• 比如，找一些能在 Arduino 微控制器上運行的代碼，覺得 https://github.com/schacon/blink 中的代碼不錯：

• 但是有個問題，這個代碼中的的閃爍頻率太高，我們覺得 3 秒一次比 1 秒一次更好一些，所以來改進這個程序，并將修改后的代碼提交給這個項目。
• 首先，單擊“Fork”按鈕來獲得這個項目的副本，我們使用的用戶名是“Kody-Y”，所以這個項目副本的訪問地址是：https://github.com/Kody-Y/blink，將它克隆到本地，創建一個分支，修改代碼，最后再將改動推送到 GitHub：

$ git clone https://github.com/Kody-Y/blink (1) Cloning into 'blink'...$ cd blink $ git checkout -b slow-blink (2) Switched to a new branch 'slow-blink'$ sed -i '' 's/1000/3000/' blink.ino (macOS) (3) # If you're on a Linux system, do this instead: # $ sed -i 's/1000/3000/' blink.ino (3)$ git diff --word-diff (4) diff --git a/blink.ino b/blink.ino index 15b9911..a6cc5a5 100644 --- a/blink.ino +++ b/blink.ino @@ -18,7 +18,7 @@ void setup() { // the loop routine runs over and over again forever: void loop() {digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level)[-delay(1000);-]{+delay(3000);+} // wait for a seconddigitalWrite(led, LOW); // turn the LED off by making the voltage LOW[-delay(1000);-]{+delay(3000);+} // wait for a second }$ git commit -a -m 'three seconds is better' (5) [slow-blink 5ca509d] three seconds is better1 file changed, 2 insertions(+), 2 deletions(-)$ git push origin slow-blink (6) Username for 'https://github.com': Kody-Y Password for 'https://Kody-Y@github.com': Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done. Total 3 (delta 1), reused 0 (delta 0) To https://github.com/Kody-Y/blink* [new branch] slow-blink -> slow-blink

• 說明：
• • (1) 將派生出的副本克隆到本地；
• • (2) 創建出名稱有意義的分支；
• • (3) 修改代碼；
• • (4) 檢查改動；
• • (5) 將改動提交到分支中；
• • (6) 將新分支推送到 GitHub 的副本中。
• 現在到 GitHub 上查看之前的項目副本，可以看到 GitHub 提示我們有新的分支，并且顯示了一個大大的綠色按鈕讓我們可以檢查我們的改動，并給源項目創建拉取請求。也可以到“Branches”（分支）頁面查看分支并創建拉取請求： https://github.com/<用戶名>/<項目名>/branches。

• 如果我們點擊那個綠色按鈕，就會跳到一個新頁面，在這里可以為拉取請求填寫標題和描述，花點時間編寫一個清晰有用的描述是非常值得的，這能讓原項目擁有者明白做了什么，為什么這個改動是正確的，以及接受此更改是否能夠改進他的項目。
• 同時我們也能看到比主分支中所“領先”（ahead）的提交（在這個例子中只有一個）以及所有將會被合并的改動與之前代碼的對比：

• 當單擊了“Create pull request”（創建拉取請求）的按鈕后，這個項目的擁有者將會收到一條包含關改動和拉取請求頁面的鏈接的提醒。雖然拉取請求通常是在貢獻者準備好在公開項目中提交改動的時候提交，但是也常被用在仍處于開發階段的內部項目中，因為拉取請求在提交后 依然可以加入新的改動，它也經常被用來建立團隊合作的環境，而不只是在最終階段使用。

② 利用拉取請求

• 現在，項目的擁有者可以看到我們的改動并合并它，拒絕它或是發表評論。在這里我們就當作他喜歡這個點子，但是他想要讓燈熄滅的時間比點亮的時間稍長一些。
• 接下來可能會通過電子郵件進行互動，就像我們在Git之深入解析如何使用Git的分布式工作流程與如何管理多人開發貢獻的項目中提到的工作流程那樣，但是在 GitHub，這些都在線上完成。項目的擁有者可以審查修改，只需要單擊某一行，就可以對其發表評論。

• 當維護者發表評論后，提交拉取請求的人，以及所有正在關注（Watching）這個版本庫的用戶都會收到通知。我們待會兒將會分析如何修改這項設置。現在，如果有開啟電子郵件提醒，將會收到這樣的一封郵件：

• 每個人都能在拉取請求中發表評論，在如下頁面里，可以看到項目擁有者對某行代碼發表評論，并在討論區留下了一個普通評論，可以看到被評論的代碼也會在互動中顯示出來：

• 現在貢獻者可以看到如何做才能讓他們的改動被接受。幸運的是，這也是一件輕松的事情，如果使用的是電子郵件進行交流，需要再次對代碼進行修改并重新提交至郵件列表，這些修改會自動更新到拉取請求上。在如下頁面中，也可以在更新后的拉取請求中看到已折疊的舊代碼評論， 因為它是在修改后的行上添加的評論：

• 對現有的拉取請求添加提交并不會觸發提醒，因此在推送了他的修正后，還需要通過評論告知項目擁有者完成了修改請求。
• 如果點開拉取請求的“Files Changed”（更改的文件）選項卡，將會看到“整理過的”差異表，也就是這個分支被合并到主分支之后將會產生的所有改動，其實就是 git diff master…<分支名> 命令的執行結果。
• 還會注意到，GitHub 會檢查拉取請求是否能直接合并，如果可以，將會提供一個按鈕來進行合并操作。這個按鈕只在對版本庫有寫入權限并且可以進行簡潔合并時才會顯示，點擊后 GitHub 將做出一個“非快進式”（non-fast-forward）合并， 即使這個合并能夠快進式（fast-forward）合并，GitHub 依然會創建一個合并提交。
• 如果需要，還可以將分支拉取并在本地合并，如果將這個分支合并到 master 分支中并推送到 GitHub，這個拉取請求會被自動關閉。這就是大部分 GitHub 項目使用的工作流程，創建分支，基于分支創建拉取請求，進行討論， 根據需要繼續在分支上進行修改，最終關閉或合并拉取請求。
• 可以在同一個版本庫中不同的分支提交拉取請求，如果正在和某人實現某個功能，而且對項目有寫權限，可以推送分支到版本庫，并在 master 分支提交一個拉取請求并在此進行代碼審查和討論的操作，不需要進行“Fork”。

三、拉取請求的進階用法

• 目前，學會了如何在 GitHub 平臺對一個項目進行最基礎的貢獻，現在有一些小技巧可以更加有效率地使用拉取請求。

① 將拉取請求制作成補丁

• 許多項目并不認為拉取請求可以作為補丁，就和通過郵件列表工作的的項目對補丁貢獻的看法一樣，大多數的 GitHub 項目將拉取請求的分支當作對改動的交流方式，并將變更集合起來統一進行合并。這是個重要的差異，因為一般來說改動會在代碼完成前提出，這和基于郵件列表的補丁貢獻有著天差地別，這使得維護者們可以更早的溝通，由社區中的力量能提出更好的方案。當有人從拉取請求提交了一些代碼，并且維護者和社區提出了一些意見，這個補丁系列并不需要從頭來過，只需要將改動重新提交并推送到分支中，這使得討論的背景和過程可以齊頭并進。
• 舉個例子，可以回去看看上文中的最終的拉取請求，會注意到貢獻者沒有變基他的提交再提交一個新的拉取請求， 而是直接增加了新的提交并推送到已有的分支中。如果之后再回去查看這個拉取請求，可以輕松地找到這個修改的原因，點擊網頁上的“Merge”（合并）按鈕后，會建立一個合并提交并指向這個拉取請求，就可以很輕松的研究原來的討論內容。

② 與上游保持同步

• 如果拉取請求由于過時或其他原因不能干凈地合并，需要進行修復才能讓維護者對其進行合并，GitHub 會對每個提交進行測試，判斷拉取請求能否簡潔的合并。

• 如果看到了像如上所示的“不能進行干凈合并”中的畫面，就需要修復分支讓這個提示變成綠色，這樣維護者就不需要再做額外的工作。有兩種方法來解決這個問題：可以把我們的分支變基到目標分支中去 （通常是派生出的版本庫中的 master 分支），或者可以合并目標分支到我們的分支中去。
• GitHub 上的大多數的開發者會使用后一種方法，基于我們在之前提到的理由：最看重的是歷史記錄和最后的合并，變基除了帶來看上去簡潔的歷史記錄，只會讓工作變得更加困難且更容易犯錯。如果想要合并目標分支來讓拉取請求變得可合并，需要將源版本庫添加為一個新的遠端，并從遠端抓取內容，合并主分支的內容到我們的分支中去，修復所有的問題并最終重新推送回提交拉取請求使用的分支。
• 在這個例子中，我們再次使用之前的用戶來進行示范，源作者提交了一個改動，使得拉取請求和它產生了沖突。現在來看解決這個問題的步驟：

$ git remote add upstream https://github.com/schacon/blink (1)$ git fetch upstream (2) remote: Counting objects: 3, done. remote: Compressing objects: 100% (3/3), done. Unpacking objects: 100% (3/3), done. remote: Total 3 (delta 0), reused 0 (delta 0) From https://github.com/schacon/blink* [new branch] master -> upstream/master$ git merge upstream/master (3) Auto-merging blink.ino CONFLICT (content): Merge conflict in blink.ino Automatic merge failed; fix conflicts and then commit the result.$ vim blink.ino (4) $ git add blink.ino $ git commit [slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \into slower-blink$ git push origin slow-blink (5) Counting objects: 6, done. Delta compression using up to 8 threads. Compressing objects: 100% (6/6), done. Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done. Total 6 (delta 2), reused 0 (delta 0) To https://github.com/tonychacon/blinkef4725c..3c8d735 slower-blink -> slow-blink

• 說明：
• • (1) 將源版本庫添加為一個遠端，并命名為“upstream”（上游）；
• • (2) 從遠端抓取最新的內容；
• • (3) 將該倉庫的主分支的內容合并到你的分支中；
• • (4) 修復產生的沖突；
• • (5) 再推送回同一個分支。
• 完成了上面的步驟后，拉取請求將會自動更新并重新檢查是否能干凈的合并：

• Git 的偉大之處就是可以一直重復以上操作，如果有一個運行了十分久的項目，可以輕松地合并目標分支且只需要處理最近的一次沖突，這使得管理流程更加容易。
• 如果一定想對分支做變基并進行清理，可以這么做，但是強烈建議不要強行地提交到已經提交了拉取請求的分支，如果其他人拉取了這個分支并進行一些修改，將會遇到Git之深入解析Git的殺手級特性·分支管理與分支變基的開發工作流以及遠程分支的跟蹤中提到的變基風險問題。相對的，將變基后的分支推送到 GitHub 上的一個新分支中，并且創建一個全新的拉取請求引用舊的拉取請求，然后關閉舊的拉取請求。

② 參考

• 下個問題可能是“該如何引用舊的拉取請求？”，有許多方法可以在 GitHub 上的幾乎任何地方引用其他東西。先從如何對拉取請求或議題（Issue）進行相互引用開始，所有的拉取請求和議題在項目中都會有一個獨一無二的編號。
• 舉個例子，無法同時擁有 3 號拉取請求和 3 號議題，如果想要引用任何一個拉取請求或議題，只需要在提交或描述中輸入 #<編號> 即可，也可以指定引用其他版本庫的議題或拉取請求，如果想要引用其他人對該版本庫的“Fork”中的議題或拉取請求， 輸入 用戶名#<編號> ，如果在不同的版本庫中，輸入 用戶名/版本庫名#<編號> 。
• 來看一個例子：假設對上個例子中的分支進行了變基，并為此創建一個新的拉取請求，現在希望能在新的拉取請求中引用舊的拉取請求，同時希望引用一個派生出的項目中的議題和一個完全不同的項目中的議題，就可以像如下所的這樣填寫描述：

• 當提交了這個拉取請求，將會看到以上內容被渲染成這樣：

• 我們會注意到完整的 GitHub 地址被簡化了，只留下了必要的信息。如果回去關閉了源拉取請求，可以看到一個被引用的提示，GitHub 會自動的反向追蹤事件并顯示在拉取請求的時間軸上，這意味著任何查看這個拉取請求的人可以輕松地訪問新的拉取請求。這個鏈接就像如下展示的那樣：

• 除了議題編號外，還可以通過使用提交的 SHA-1 來引用提交，必須完整的寫出 40 位長的 SHA-1，GitHub 會在評論中自動地產生指向這個提交的鏈接。 同樣的，可以像引用議題一樣對派生的項目中的提交或者其他項目中的提交進行引用。

四、GitHub 風格的 Markdown

• 對于在 GitHub 中絕大多數文本框中能夠做到的事，引用其他議題只是個開始。在議題和拉取請求的描述，評論和代碼評論還有其他地方，都可以使用“GitHub 風格的 Markdown”。Markdown 可以輸入純文本，但是渲染出豐富的內容。
• 通過如下示例了解如何書寫評論或文本，并通過 Markdown 進行渲染：

① GitHub 風格的 Markdown

• GitHub 風格的 Markdown 增加了一些基礎的 Markdown 中做不到的東西，它在創建拉取請求和議題中的評論和描述時十分有用。
• 第一個 GitHub 專屬的 Markdown 功能，特別是用在拉取請求中，就是任務列表，一個任務列表可以展示出一系列我們想要完成的事情，并帶有復選框，把它們放在議題或拉取請求中時，通常可以展示想要完成的事情。
• 可以這樣創建一個任務列表：

- [X] 編寫代碼- [ ] 編寫所有測試程序- [ ] 為代碼編寫文檔

• 如果我們將這個列表加入拉取請求或議題的描述中，它將會被渲染這樣：

• 在拉取請求中，任務列表經常被用來在合并之前展示這個分支將要完成的事情。最酷的地方就是，只需要點擊復選框，就能更新評論，不需要直接修改 Markdown。
• 不僅如此，GitHub 還會將在議題和拉取請求中的任務列表整理起來集中展示。舉個例子，如果在一個拉取請求中有任務清單，將會在所有拉取請求的總覽頁面上看到它的進度，這使得人們可以把一個拉取請求分解成不同的小任務，同時便于其他人了解分支的進度：

• 當在實現一個任務的早期就提交拉取請求，并使用任務清單追蹤你的進度，這個功能會十分的有用。

② 代碼片段

• 也可以在評論中添加代碼片段，這在想要展示尚未提交到分支中的代碼時會十分有用。它也經常被用在展示無法正常工作的代碼或這個拉取請求需要的代碼。
• 需要用“反引號”將需要添加的代碼片段包起來：

// java for(int i=0 ; i < 5 ; i++) {System.out.println("i is : " + i); }

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

③ 引用

• 如果在回復一個很長的評論之中的一小段，只需要復制需要的片段，并在每行前添加 > 符號即可。事實上，因為這個功能會被經常用到，它也有一個快捷鍵。只要把要回應的文字選中，并按下 r 鍵，選中的問題會自動引用并填入評論框。
• 引用的部分就像這樣:

> Whether 'tis Nobler in the mind to suffer > The Slings and Arrows of outrageous Fortune,How big are these slings and in particular, these arrows?

• 經過渲染后，就會變成這樣：

④ 表情符號

• 最后，我們可以在評論中使用表情符號，這經常出現在 GitHub 的議題和拉取請求的評論中。GitHub 上甚至有表情助手，如果在輸入評論時以 : 開頭，自動完成器會幫助我們找到需要的表情：

• 也可以在評論的任何地方使用 :<表情名稱>: 來添加表情符號。舉個例子，可以輸入以下文字：

I :eyes: that :bug: and I :cold_sweat:.:trophy: for :microscope: it.:+1: and :sparkles: on this :ship:, it's :fire::poop:!:clap::tada::panda_face:

• 渲染之后，就會變成這樣：

• 雖然這個功能并不是非常實用，但是它在這種不方便表達感情的媒體里，加入了趣味的元素。

⑤ 圖片

• 從技術層面來說，這并不是 GitHub 風格 Markdown 的功能，但是也很有用。如果不想使用 Markdown 語法來插入圖片，GitHub 允許通過拖拽圖片到文本區來插入圖片：

• 可以發現文本區上有個“Parsed as Markdown”的提示，點擊它可以了解所有能在 GitHub 上使用的 Markdown 功能。

五、讓 GitHub 公共倉庫保持更新

• 當派生了一個 GitHub 倉庫之后，倉庫（即“派生”）會獨立于原倉庫而獨立。特別地，當原倉庫有新的提交時，GitHub 會通知：

This branch is 5 commits behind progit:master. （本分支落后 progit:master 5 個提交）

• 但 GitHub 倉庫不會被 GitHub 自動更新，這件事必須由自己來做。
• 第一種方法無需配置，例如，若從 https://github.com/progit/progit2.git 派生了項目，可以像這樣更新 master 分支：

$ git checkout master (1) $ git pull https://github.com/progit/progit2.git (2) $ git push origin master (3)

• 分析：
• • (1) 如果在另一個分支上，就切換到 master；
• • (2) 從 https://github.com/progit/progit2.git 抓取更改后合并到 master；
• • (3) 將 master 分支推送到 origin。
• 這雖然可行，但每次都要輸入從哪個 URL 抓取有點麻煩，可以稍微設置一下來自動完成它：

$ git remote add progit https://github.com/progit/progit2.git (1) $ git branch --set-upstream-to=progit/master master (2) $ git config --local remote.pushDefault origin (3)

• 分析：

• • (1) 添加源倉庫并取一個名字，這里叫它 progit；
• • (2) 將 master 分支設置為從 progit 遠端抓取；
• • (3) 將默認推送倉庫設置為 origin。

• 搞定之后，工作流程為更加簡單：

$ git checkout master (1) $ git pull (2) $ git push (3)

• 分析：
• • (1) 如果在另一個分支上，就切換到 master；
• • (2) 從 progit 抓取更改后合并到 master；
• • (3) 將 master 分支推送到 origin。
• 這種方法非常有用，而且沒有缺點。Git 非常樂意暗中做這些工作，而且它不會在向 master 提交更改，從 progit 拉取更改，然后向 origin 推送時通知，所有這些操作在這種配置下都是有效的。因此不必對直接提交到 master 有所顧慮，因為該分支從效果上來說屬于上游倉庫。

總結

以上是生活随笔為你收集整理的GitHub之深入解析如何对项目做出贡献的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。