如何參與開源項目 - 細(xì)說 GitHub 上的 PR 全過程

一、概述

今天我準(zhǔn)備和你詳細(xì)介紹如何開始參與開源項目，幫助你在 GitHub 上完成第一個 PR 的合入。

當(dāng)然，除了正常的 PR 合入流程之外，我還準(zhǔn)備詳細(xì)介紹一下如果一個 PR 提交后遇到了沖突、需要追加 commits、需要合并 commits 等等相對復(fù)雜問題該如何解決。

總的來說，本文計劃分為4個部分：

1. 談?wù)劄槭裁匆獏⑴c開源項目以及我為什么要介紹如何 PR
2. 談?wù)勗趺撮_始參與開源項目，也就是如何尋找合適的開源項目、如何尋找貢獻點
3. 介紹怎么上手 PR 流程，即從 fork 到 push 全流程
4. 介紹提交了 PR 之后遇到各種常見問題如何解決

Ok, let's get started!

二、為什么要參與開源項目

本文我不打算長篇大論“為什么要參與開源”，詳細(xì)介紹參與開源項目的收獲，我想僅從“提升編碼能力”角度談一談“為什么要參與開源項目”。

在面試的時候我有個習(xí)慣，如果候選人在自己的簡歷里說到自己熟悉某一門語言，我就會習(xí)慣性問他一個問題：

你有沒有閱讀過某個開源項目的源碼？或者更進一步，有沒有參與過某個開源社區(qū)，或者說給開源項目提過 PR？

如果答案是肯定的，比如候選人說自己讀過部分 Kubernetes 模塊的源碼，再進一步我確認(rèn)他真的讀過并且讀懂了或者說真的提交過 bugfix/feature 類型的 PR，那我就不再問編程語言層面的問題了，因為我相信能看懂一個成熟的開源項目部分模塊源碼或者能夠提交 bugfix/feature 類型的 PR 已經(jīng)說明了一切。

我自己在學(xué)習(xí) Golang 的時候，大致分為兩個階段：

1. 學(xué)習(xí)基礎(chǔ)語法，開始寫項目，直到能夠熟練完成各種業(yè)務(wù)功能的開發(fā)；
2. 看了一些開源項目的源碼，深感受益頗多，編碼水平再上一個臺階。

差不多也就是在看 Kubernetes 項目源碼的時候，我深刻認(rèn)識到一般的企業(yè)內(nèi)部項目和匯集全世界最優(yōu)秀的程序員智慧結(jié)晶的開源項目之間的巨大差距，也意識到學(xué)習(xí)優(yōu)秀開源項目源碼對于一個程序員編碼水平提升的重要性（當(dāng)然，你可以說 Google 內(nèi)部也存在非開源的非常優(yōu)秀的代碼，這毫無疑問，但是我想今天我們沒有必要討論特例）。

認(rèn)真閱讀開源項目源碼，你總會發(fā)現(xiàn)一些小瑕疵，這時候提一個 PR(Pull Request)，讓你的代碼合入開源項目，運行在“世界每一個角落”，那是多么有趣的事情！而成功合入第一個 PR 往往就像打開潘多拉魔盒一樣，你會進入到另外一個世界，開始接觸到開源社區(qū)，感受開源的魅力！

三、為什么我想介紹如何 PR

我司開源了2個項目，分別是：

1. CNCF Project DevStream^[1]

2. Apache DevLake^[2]

DevStream 項目和 DevLake 項目隔三差五就會有新貢獻者提交 PR 過來，但是多數(shù)貢獻者在提交第一個 PR 時往往會遇到一個或多個問題，比如產(chǎn)生沖突、commits 記錄過多或者混亂、commit 沒有簽名、commit message 不規(guī)范、各種 ci 流程檢查報錯等等。

在看到新貢獻者提交 PR 時，我們自然是非常開心且熱情地對他表示歡迎并且告知如何修復(fù)各種問題，但是隨著貢獻者的增多，我們的開源社區(qū)幾乎每天都需要回答一個問題：“如何正確地提交一個 PR”。可能此時你會開始懷疑我們是不是沒有提供相應(yīng)的文檔？其實不然，我們有詳細(xì)的文檔，但是人總是有惰性的，多數(shù)的新貢獻者并沒有足夠的意愿去仔細(xì)看翻看文檔然后再提交 PR，甚至很多新貢獻者由于剛開始接觸開源項目，對于項目結(jié)構(gòu)和文檔組織結(jié)構(gòu)比較陌生，甚至不會想到有這些文檔的存在，總之各種各樣的理由讓多數(shù)的新貢獻者會選擇“先提了 PR再說”。

那么今天我想嘗試徹底講明白“如何正確地提交一個 PR”，嘗試細(xì)說 GitHub 上的 PR 全過程，以及這里面可能會遇到的各種困難和解決辦法。一方面希望對第一次參與開源項目的新人有所幫助，另一方面希望能夠進一步降低 DevStream 社區(qū)和 DevLake 社區(qū)的參與門檻。

四、我想?yún)⑴c開源項目，怎么開始？

不管你為什么決定開始參與開源項目，不管出發(fā)點是出于學(xué)習(xí)、興趣、成就感等等，還是為了讓某個自己需要的特性合入某個開源項目，總之今天你下定決心，要給某個開源項目提交一個 PR 了，好，我們開始吧！

4.1、尋找一個合適的開源項目

如果你已經(jīng)決定參與某個開源社區(qū)了，那么請直接跳過本小節(jié)。

如果你就只是想開始參與開源，暫時還不知道該參與哪個社區(qū)，那么我有幾個小建議：

1. 不要從特別成熟的項目開始。比如現(xiàn)在去參與 Kubernetes 社區(qū)，一方面由于貢獻者太多，很難搶到一個入門級的 issue 來開始第一個 PR；另外一方面也由于貢獻者太多，你的聲音會被淹沒，社區(qū)維護者并不在意多你一個或者少你一個（當(dāng)然可能沒有人會承認(rèn)，但是你不得不信），如果你提個 PR 都遇到了各種問題還不能自己獨立解決，那么很可能你的 PR 會直接超時關(guān)閉，沒有人在意你是不是有一個好的參與體驗；
2. 不要從特別小的項目開始。這就不需要我解釋了吧？很早期的開源項目可能面臨著非常多的問題，比如代碼不規(guī)范、協(xié)作流程不規(guī)范、重構(gòu)頻繁且不是 issue 驅(qū)動的，讓外部參與者無所適從……
3. 選擇知名開源軟件基金會的孵化項目，這類項目一方面不是特別成熟，所以對新貢獻者友好；另一方面也不會特別不成熟，不至于給人很差的參與體驗，比如 Apache 基金會、Linux 基金會、CNCF 等。

比如可以從這些地方尋找自己感興趣的開源項目：

• CNCF 沙箱項目^[3]
• CNCF 孵化項目(列表包括畢業(yè)項目)^[4]
• Apache 項目(孵化期項目名字中帶 Incubating)^[5]

當(dāng)然，你也可以直接選擇從 CNCF 沙箱項目 DevStream^[6] 或者 Apache 孵化項目 Apache DevLake^[7]，以此敲開開源世界的大門。

4.2、尋找貢獻點

開源項目的參與方式很多，最典型的方式是提交一個特性開發(fā)或者 bug 修復(fù)相關(guān)的 PR，但是其實文檔完善、測試用例完善、bug 反饋等等也都是非常有價值的貢獻。不過本文還是從需要提 PR 的貢獻點開始上手，以 DevStream 項目為例（其他項目也一樣），在項目 GitHub 代碼庫首頁都會有一個 Issues 入口^[8]，這里會記錄項目目前已知的 bug、proposal(可以理解成新需求)、計劃補充的文檔、亟需完善的 UT 等等，如下圖：

在 Issues 里我們一般可以找到一個“good first issue”標(biāo)簽標(biāo)記的 issues，點擊這個標(biāo)簽可以進一步直接篩選出所有的 good first issues，這是社區(qū)專門留給新貢獻者的相對簡單的入門級 issues：

沒錯，從這里開始，瀏覽一下這些 good first issues，看下有沒有你感興趣的而且還沒被分配的 issue，然后在下面留言，等待項目管理員分配任務(wù)后就可以開始編碼了，就像這樣：

如圖所示，如果一個 issue 還沒有被認(rèn)領(lǐng)，這時候你上去留個言，等待管理員會將這個任務(wù)分配給你，接著你就可以開始開發(fā)了。

五、我要提交 PR，怎么上手？

一般開源項目代碼庫根目錄都會有一個 CONTRIBUTING.md 或者其他類似名字的文檔來介紹如何開始貢獻，像這樣：

在 DevStream 的 Contributing^[9] 文檔里我們放了一個 Development Workflow^[10]，其實就是 PR 工作流的介紹，不過今天，我要更詳細(xì)地聊聊 PR 工作流。

5.1、第一步：Fork 項目倉庫

GitHub 上的項目都有一個 Fork 按鈕，我們需要先將開源項目 fork 到自己的賬號下，以 DevStream 為例：

點一下 Fork 按鈕，然后回到自己賬號下，可以找到 fork 到的項目了：

這個項目在你自己的賬號下，也就意味著你有任意修改的權(quán)限了。我們后面要做的事情，就是將代碼變更提到自己 fork 出來的代碼庫里，然后再通過 Pull Request 的方式將 commits 合入上游項目。

5.2、第二步：克隆項目倉庫到本地

對于任意一個開源項目，流程幾乎都是一樣的。我直接寫了一些命令，大家可以復(fù)制粘貼直接執(zhí)行。當(dāng)然，命令里的一些變量還是需要根據(jù)你自己的實際需求修改，比如對于 DevStream 項目，我們可以先這樣配置幾個環(huán)境變量：

• 環(huán)境變量

export WORKING_PATH="~/gocode"
export USER="daniel-hutao"
export PROJECT="devstream"
export ORG="devstream-io"

同理對于 DevLake，這里的命令就變成了這樣：

export WORKING_PATH="~/gocode"
export USER="daniel-hutao"
export PROJECT="incubator-devlake"
export ORG="apache"

記得 USER 改成你的 GitHub 用戶名，WORKING_PATH 當(dāng)然也可以靈活配置，你想把代碼放到哪里，就寫對應(yīng)路徑。

接著就是幾行通用的命令來完成 clone 等操作了：

• clone 等

mkdir -p ${WORKING_PATH}
cd ${WORKING_PATH}
# You can also use the url: [email protected]:${USER}/${PROJECT}.git
# if your ssh configuration is proper
git clone https://github.com/${USER}/${PROJECT}.git
cd ${PROJECT}

git remote add upstream https://github.com/${ORG}/${PROJECT}.git
# Never push to upstream locally
git remote set-url --push upstream no_push

如果你配置好了 ssh 方式來 clone 代碼，當(dāng)然，git clone 命令用的 url 可以改成[email protected]:${USER}/${PROJECT}.git。

完成這一步后，我們在本地看到的 remote 信息應(yīng)該是這樣的：

• git remote -v

origin	[email protected]:daniel-hutao/devstream.git (fetch)
origin	[email protected]:daniel-hutao/devstream.git (push)
upstream	https://github.com/devstream-io/devstream (fetch)
upstream	no_push (push)

記住啰，你本地的代碼變更永遠只提交到 origin，然后通過 origin 提交 Pull Request 到 upstream。

5.3、第三步：更新本地分支代碼

如果你剛剛完成 fork 和 clone 操作，那么你本地的代碼肯定是新的。但是“剛剛”只存在一次，接著每一次準(zhǔn)備開始寫代碼之前，你都需要確認(rèn)本地分支的代碼是新的，因為基于老代碼開發(fā)你會陷入無限的沖突困境之中。

• 更新本地 main 分支代碼：

git fetch upstream
git checkout main
git rebase upstream/main

當(dāng)然，我不建議你直接在 main 分支寫代碼，雖然你的第一個 PR 從 main 提交完全沒有問題，但是如果你需要同時提交2個 PR 呢？總之鼓勵新增一個 feat-xxx 或者 fix-xxx 等更可讀的分支來完成開發(fā)工作。

• 創(chuàng)建分支

git checkout -b feat-xxx

這樣，我們就得到了一個和上游 main 分支代碼一樣的特性分支 feat-xxx 了，接著可以開始愉快地寫代碼啦！

5.4、第四步：寫代碼

沒啥好說的，寫就是了，寫！

5.5、第五步：Commit 和 Push

• 通用的流程：

git add <file>
git commit -s -m "some description here"
git push origin feat-xxx

當(dāng)然，這里大家需要理解這幾個命令和參數(shù)的含義，靈活調(diào)整。比如你也可以用git add --all完成 add 步驟，在 push 的時候也可以加-f參數(shù)，用來強制覆蓋遠程分支（假如已經(jīng)存在，但是 commits 記錄不合你意）。但是請記得git commit的-s參數(shù)一定要加哦！

如果你習(xí)慣用 IDE 來 commit，當(dāng)然也沒有任何問題，像這樣：

這里要注意 commit message 的規(guī)范，可能每個開源項目的要求不盡相同，比如 DevStream 的規(guī)范^[11]是類似這樣的格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

舉幾個例子：

• feat: some description here
• docs: some description here
• fix: some description here
• fix(core): some description here
• chore: some description here
• ...

commit 和 push 兩個步驟可以在 IDE 里一步到位，也可以分開，我習(xí)慣分開操作，給自己多一些余地。另外，我更習(xí)慣命令行操作：

• git push origin feat-1

Counting objects: 80, done.
Delta compression using up to 10 threads.
Compressing objects: 100% (74/74), done.
Writing objects: 100% (80/80), 13.78 KiB | 4.59 MiB/s, done.
Total 80 (delta 55), reused 0 (delta 0)
remote: Resolving deltas: 100% (55/55), completed with 31 local objects.
remote: 
remote: Create a pull request for 'feat-1' on GitHub by visiting:
remote:      https://github.com/daniel-hutao/devstream/pull/new/feat-1
remote: 
To github.com:daniel-hutao/devstream.git
 * [new branch]      feat-1 -> feat-1

到這里，本地 commits 就推送到遠程了。

5.6、第六步：開一個 PR

在完成 push 操作后，我們打開 GitHub，可以看到一個黃色的提示框，告訴我們可以開一個 Pull Request 了：

如果你沒有看到這個框，也可以直接切換到 feat-1 分支，然后點擊下方的“Contribute”按鈕來開啟一個 PR，或者直接點 Issues 邊上的 Pull requests 進入對應(yīng)頁面。

• Pull Request 格式默認(rèn)是這樣的：

這里我們需要填寫一個合適的標(biāo)題（默認(rèn)和 commit message 一樣），然后按照模板填寫 PR 描述。PR 模板其實在每個開源項目里都不太一樣，我們需要仔細(xì)閱讀上面的內(nèi)容，避免犯低級錯誤。

比如 DevStream 的模板里目前分為4個部分：

1. Pre-Checklist：這里列了3個前置檢查項，提醒 PR 提交者要先閱讀 Contributing 文檔，然后代碼要有完善的注釋或者文檔，盡可能添加測試用例等；
2. Description：這里填寫的是 PR 的描述信息，也就是介紹你的 PR 內(nèi)容的，你可以在這里描述這個 PR 解決了什么問題等；
3. Related Issues：記得嗎？我們在開始寫代碼之前其實是需要認(rèn)領(lǐng) issue 的，這里要填寫的也就是對應(yīng) issue 的 id，假如你領(lǐng)的 issue 鏈接是 https://github.com/devstream-io/devstream/issues/796，并且這個 issue 通過你這個 PR 的修改后就完成了，可以關(guān)閉了，這時候可以在 Related Issues 下面寫“close #796”；
4. New Behavior：代碼修改后絕大多數(shù)情況下是需要進行測試的，這時候我們可以在這里粘貼測試結(jié)果截圖，這樣 reviewers 就能夠知道你的代碼已經(jīng)通過測試，功能符合預(yù)期，這樣可以減少 review 工作量，快速合入。

這個模板并不復(fù)雜，我們直接對著填寫就行。

• 比如：

然后點擊右下角“Create pull request”就完成了一個 PR 的創(chuàng)建了。不過我這里不能去點這個按鈕，我用來演示的修改內(nèi)容沒有意義，不能合入上游代碼庫。不過我還是想給你看下 PR 創(chuàng)建出來后的效果，我們以 pr655^[12] 為例吧：

這是上個月我提的一個 PR，基本和模板格式一致。除了模板的內(nèi)容，可能你已經(jīng)注意到這里多了一個 Test 小節(jié)，沒錯，模板不是死的，模板只是為了降低溝通成本，你完全可以適當(dāng)調(diào)整，只要結(jié)果是“往更清晰的方向走”的。我這里通過 Test 部分添加了本地詳細(xì)測試結(jié)果記錄，告訴 reviewers 我已經(jīng)在本地充分測試了，請放心合入。

提交了 PR 之后，我們就可以在 PR 列表里找到自己的 PR 了，這時候還需要注意 ci 檢查是不是全部能夠通過，假如失敗了，需要及時修復(fù)。以 DevStream 為例，ci 檢查項大致如下：

5.7、第七步：PR 合入

如果你的 PR 很完美，毫無爭議，那么過不了太長時間，項目管理員會直接合入你的 PR，那么你這個 PR 的生命周期也就到此結(jié)束了。

但是，沒錯，這里有個“但是”，但是往往第一次 PR 不會那么順利，我們接下來就詳細(xì)介紹一下可能經(jīng)常遇到的一些問題和對應(yīng)的解決辦法。

六、我提交了一個 PR，然后遇到了問題 A,B,C,D,E,F,G,...??

多數(shù)情況下，提交一個 PR 后是不會被馬上合入的，reviewers 可能會提出各種修改意見，或者我們的 PR 本身存在一些規(guī)范性問題，或者 ci 檢查就直接報錯了，怎么解決呢？繼續(xù)往下看吧。

6.1、Reviewers 提了一些修改意見，我如何更新 PR？

很多時候，我們提交了一個 PR 后，還需要繼續(xù)追加 commit，比如提交后發(fā)現(xiàn)代碼還有點問題，想再改改，或者 reviewers 提了一些修改意見，我們需要更新代碼。

一般我們遵守一個約定：在 review 開始之前，更新代碼盡量不引入新的 commits 記錄，也就是能合并就合并，保證 commits 記錄清晰且有意義；在 review 開始之后，針對 reviewers 的修改意見所產(chǎn)生的新 commit，可以不向前合并，這樣能夠讓二次 review 工作更有針對性。

不過不同社區(qū)要求不一樣，可能有的開源項目會要求一個 PR 里只能包含一個 commit，大家根據(jù)實際場景靈活判斷即可。

說回如何更新 PR，我們只需要在本地繼續(xù)修改代碼，然后通過和第一個 commit 一樣的步驟，執(zhí)行這幾個命令：

git add <file>
git commit -s -m "some description here"
git push origin feat-xxx

這時候別看 push 的是 origin 的 feat-xxx 分支，其實 GitHub 會幫你把新增的 commits 全部追加到一個未合入 PR 里去。沒錯，你只管不斷 push，PR 會自動更新。

至于如何合并 commits，我們下一小節(jié)具體介紹。

6.2、Commits 太多或者記錄混亂，如何合并 Commits？

很多情況下我們需要去合并 commits，比如你的第一個 commit 里改了100行代碼，然后發(fā)現(xiàn)少改了1行，這時候又提交了一個 commit，那么第二個 commit 就太“沒意思”了，我們需要合并一下。

6.2.1、Git 命令行方式合并 Commits

比如我這里有2個同名的 commits，第二個 commit 其實只改了一個標(biāo)點：

這時候我們可以通過 rebase 命令來完成2個 commits 的合并：

git rebase -i HEAD~2

執(zhí)行這個命令會進入一個編輯頁面，默認(rèn)是 vim 編輯模式，內(nèi)容大致如下：

pick 3114c0f docs: just for test
pick 9b7d63b docs: just for test

# Rebase d640931..9b7d63b onto d640931 (2 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.

我們需要把第二個 pick 改成 s，然后保存退出(vim 的 wq 命令)：

pick 3114c0f docs: just for test
s 9b7d63b docs: just for test

接著會進入第二個編輯頁面：

# This is a combination of 2 commits.
# This is the 1st commit message:

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

# This is the commit message #2:

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# ...

這里是用來編輯合并后的 commit message 的，我們直接刪掉多余部分，只保留這樣幾行：

docs: just for test

Signed-off-by: Daniel Hu <[email protected]>

接著同樣是 vim 的保存退出操作，這時候可以看到日志：

[detached HEAD 80f5e57] docs: just for test
 Date: Wed Jul 6 10:28:37 2022 +0800
 1 file changed, 2 insertions(+)
Successfully rebased and updated refs/heads/feat-1.

這時候可以通過git log命令查看下 commits 記錄是不是符合預(yù)期：

好，我們在本地確認(rèn) commits 已經(jīng)完成合并，這時候就可以繼續(xù)推送到遠程，讓 PR 也更新掉：

git push -f origin feat-xxx

這里需要有一個-f參數(shù)來強制更新，合并了 commits 本質(zhì)也是一種沖突，需要沖掉遠程舊的 commits 記錄。

6.2.2 IDE 里合并 Commits

圖形化方式當(dāng)然也可以實現(xiàn) Commits 的合并。

• 截圖走起

1. 點擊右下角的 Git
2. 選擇想要合并的 commits
3. 右鍵，然后點擊 Squash Commits，記得嘴里默念一句：走你！

接著就可以看到這個頁面了：

這是圖形化方式修改 commit message 的頁面，行吧，改成你喜歡的樣子，然后點擊右下角的 OK 按鈕，事情就算結(jié)束了。

看，2個 commits，它們“融合”了，變成了一個“改頭換面”的新 commit 了。

6.3、PR 產(chǎn)生了沖突，如何解決？

沖突可以在線解決，也可能本地解決，我們逐個來看。

6.3.1、在線解決沖突

我們要盡可能避免沖突，養(yǎng)成每次寫代碼前更新本地代碼的習(xí)慣。不過，沖突不可能完全避免，有時候你的 PR 被阻塞了幾天，可能別人改了同一行代碼，還搶先被合入了，這時候你的 PR 就出現(xiàn)沖突了，類似這樣（同樣，此刻我不能真的去上游項目構(gòu)造沖突，所以下面用于演示的沖突在我在自己的 repo 里）：

每次看到這個頁面都會讓人覺得心頭一緊。我們點擊“Resolve conflicts”按鈕，就可以看到具體沖突的內(nèi)容了：

可以看到具體沖突的行了，接下來要做的就是解決沖突。我們需要刪掉所有的 <<<<<<<、>>>>>>> 和 ======= 標(biāo)記，只保留最終想要的內(nèi)容，如下：

接著點擊右上角的“Mark as Resolved”：

最后點擊“Commit merge”：

這樣就完成沖突解決了，可以看到產(chǎn)生了一個新的 commit：

到這里，沖突就解決掉了。

6.3.2、本地解決沖突

更多時候，我們需要在本地解決沖突，尤其是沖突太多，太復(fù)雜的時候。

同樣，我們構(gòu)造一個沖突，這次嘗試在本地解決沖突。

• 先在線看一下沖突的內(nèi)容：

• 接著我們在本地執(zhí)行：

# 先切回到 main 分支
git checkout main
# 拉取上游代碼（實際場景肯定是和上游沖突，我們這里的演示環(huán)境其實是 origin）
git fetch upstream
# 更新本地 main（這里也可以用 rebase，但是 reset 不管有沒有沖突總是會成功）
git reset --hard upstream/main

到這里，本地 main 分支就和遠程(或者上游) main 分支代碼完全一致了，然后我們要做的是將 main 分支的代碼合入自己的特性分支，同時解決沖突。

git checkout feat-1
git rebase main

• 這時候會看到這樣的日志：

First, rewinding head to replay your work on top of it...
Applying: docs: conflict test 1
Using index info to reconstruct a base tree...
M       README.md
Falling back to patching base and 3-way merge...
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
error: Failed to merge in the changes.
Patch failed at 0001 docs: conflict test 1
The copy of the patch that failed is found in: .git/rebase-apply/patch

Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".

我們需要解決沖突，直接打開 README.md，找到?jīng)_突的地方，直接修改。這里的改法和上一小節(jié)介紹的在線解決沖突沒有任何區(qū)別，我就不贅述了。

代碼里同樣只保留最終內(nèi)容，然后繼續(xù) git 命令走起來：

可能此時你并不放心，那就通過git log命令看一下 commits 歷史記錄吧：

這里的“conflict test 2”是我提交到 main 分支的記錄，可以看到這個時間比“conflict test 1”還要晚了一些，但是它先合入了。我們在 rebase 操作后，這個記錄在前，我們特性分支的“conflict test 1”在后，看起來很和諧，我們繼續(xù)將這個變更推送到遠程，這個命令已經(jīng)出現(xiàn)很多次了：

git push -f origin feat-xxx

這時候我們再回到 GitHub 看 PR 的話，可以發(fā)現(xiàn)沖突已經(jīng)解決了，并且沒有產(chǎn)生多余的 commit 記錄，也就是說這個 PR 的 commit 記錄非常干凈，好似沖突從來沒有出現(xiàn)過：

至于什么時候可以在線解決沖突，什么時候適合本地解決沖突，就看大家如何看待“需不需要保留解決沖突的記錄”了，不同社區(qū)的理解不一樣，可能特別成熟的開源社區(qū)會希望使用本地解決沖突方式，因為在線解決沖突產(chǎn)生的這條 merge 記錄其實“沒營養(yǎng)”。至于 DevStream 社區(qū)和 DevLake 社區(qū)，我們推薦使用后一種，但是不做強制要求。

6.4、CI 檢查不過：commit message 相關(guān)問題如何修復(fù)？

前面我們提到過 commit message 的規(guī)范，但是第一次提交 PR 的時候還是很容易出錯，比如feat: xxx其實能通過 ci 檢查，但是feat: Xxx就不行了。假設(shè)現(xiàn)在我們不小心提交了一個 PR，但是里面 commit 的 message 不規(guī)范，這時候怎么修改呢？

• 太簡單了，直接執(zhí)行：

git commit --amend

這條命令執(zhí)行后就能進入編輯頁面，隨意更新 commit message 了。改完之后，繼續(xù) push：

git push -f origin feat-xxx

這樣就能更新 PR 里的 commit message 了。

6.5、CI 檢查不過：DCO(sign) 問題如何修復(fù)？

相當(dāng)多的開源項目會要求所有合入的 commits 都包含一行類似這樣的記錄：

Daniel Hu <[email protected]>

所以 commit message 看起來會像這樣：

feat: some description here
    
Signed-off-by: Daniel Hu <[email protected]>

這行信息相當(dāng)于是對應(yīng) commit 的作者簽名。要添加這樣一行簽名當(dāng)然很簡單，我們直接在git commit命令后面加一個-s參數(shù)就可以了，比如git commit -s -m "some description here"提交的 commit 就會帶上你的簽名。

但是如果如果你第一次提交的 PR 里忘記了在 commits 中添加 Signed-off-by 呢？這時候，如果對應(yīng)開源項目配置了 DCO 檢查^[13]，那么你的 PR 就會在 ci 檢查中被“揪出來”沒有正確簽名。

同樣先構(gòu)造一個沒有加簽名的 commit：

我不能直接推到 DevStream 項目代碼庫里演示如何讓 DCO 報錯，但是如果提 PR，看到的效果是這樣的：

我們看下如何解決：

• git commit --amend -s

這樣一個簡單的命令，就能直接在最近一個 commit 里加上 Signed-off-by 信息。執(zhí)行這行命令后會直接進入 commit message 編輯頁面，默認(rèn)如下圖：

docs: dco test

Signed-off-by: Daniel Hu <[email protected]>

這時候我們可以同時修改 commit message，如果不需要，那就直接保存退出好了，簽名信息是會自動加上的。

完成簽名后呢？當(dāng)然是來一個強制 push 了：

git push -f origin feat-xxx

這樣，你 PR 中的 DCO 報錯就自然修復(fù)了。

七、最后

一個不小心這篇文章寫的有點長了。行，打完收工！

• 歡迎到我的個人網(wǎng)站^[14]或者微信公眾號“胡說云原生”瀏覽更多我的文章；
• 歡迎關(guān)注DevStream 社區(qū)^[15]，和我一起玩開源；
• 歡迎到DevStream 官方博客^[16]瀏覽更多 DevStream 團隊發(fā)布的文章。