以前給 Go 語言項目源碼提交過一些 commits，期間閱讀他們的官方指導文檔的時候覺得這篇指導文檔可以作為絕佳的關(guān)于大型軟件項目的規(guī)范管理的參考，因為最近又提交了幾個 commits，就又把這篇文檔再看了一遍，有感于 Go 團隊在項目管理和工程實踐上的一些寶貴經(jīng)驗，就把文檔翻譯成了中文；一來為了更加深入地理解 Go 語言團隊的項目工程最佳實踐，二來則是為了給其他有意給 Go 語言源碼提交貢獻的開發(fā)者提供一點參考。

Go 語言項目歡迎所有代碼貢獻者。

這是一份指導你完成向 Go 語言項目貢獻代碼整個流程的文檔，會略微跟其他開源項目所使用的指導文檔有所不同。我們假設閱讀者已經(jīng)對 Git 和 Go 有基本的理解以及具備相關(guān)的基礎(chǔ)知識。

除了這里所介紹的信息，Go 語言社區(qū)也維護了一份關(guān)于代碼評審的 wiki 頁面。在你學習 review 的過程中，歡迎隨時給這份 wiki 貢獻、補充新內(nèi)容。

請注意，gccgo前端的文檔在另一處；看這里：Contributing to gccgo。

成為一個代碼貢獻者

概述

第一步需要注冊成為一個 Go contributor 以及配置你的環(huán)境。這里有一份包含了所需步驟的清單：

• 步驟 0: 準備好一個你將用來給 Go 語言貢獻代碼的 Google 賬號。在后面所有的步驟中都要使用這個賬號，還有確保你的git已經(jīng)正確配置了這個賬號的郵箱地址，以便后續(xù)提交 commits。
• 步驟 1: 簽署以及提交一個 CLA(貢獻者證書協(xié)議)。
• 步驟 2: 給 Go Git 倉庫配置好權(quán)限憑證。訪問 go.googlesource.com，點擊右上角的齒輪圖標，接著點擊 "Obtain password"，然后跟著指引操作即可。
• 步驟 3: 在這個頁面注冊一個 Gerrit 賬號，它是 Go 語言團隊使用的代碼評審工具。CLA 的申請和 Gerrit 的注冊只需要在你的賬號上做一次就可以了
• 步驟 4: 運行g(shù)o get -u golang.org/x/review/git-codereview命令安裝 git-codereview 工具。

如果你圖省事的話，可以直接用自動化工具幫你做完上面的全部步驟，只需運行：

$ go get -u golang.org/x/tools/cmd/go-contrib-init
$ cd /code/to/edit
$ go-contrib-init

這個章節(jié)的后面部分將會更加詳盡地闡述上面的每一個步驟。如果你已經(jīng)完成上面的所有步驟(不管是手動還是通過自動化工具)，可以直接跳到貢獻代碼之前部分。

步驟 0: 選擇一個 Google 賬號

每一個提交到 Go 語言的代碼貢獻都是通過一個綁定了特定郵箱地址的 Google 賬號來完成的。請確保你在整個流程中自始至終使用的都是同一個賬號，當然，后續(xù)你提交的所有代碼貢獻也是如此。你可能需要想好使用哪一種郵箱，個人的還是企業(yè)的。郵箱類型的選擇將決定誰擁有你編寫和提交的代碼的版權(quán)。在決定使用哪個賬戶之前，你大概要和你的雇主商議一下。

Google 賬號可以是 Gmail 郵箱賬號、G Suite 組織賬號，或者是那些綁定了外部郵箱的賬號。例如，如果你想要使用一個已存在且并不屬于 G Suite 的企業(yè)郵箱，你可以創(chuàng)建一個綁定了外部郵箱的 Google 賬號。

你還需要確保你的 Git 工具已經(jīng)正確配置好你之前選定的郵箱地址，用來提交代碼。你可以通過 Git 命令來進行全局配置(所有項目都將默認使用這個配置)或者只進行本地配置(只指定某個特定的項目使用)?？梢酝ㄟ^以下的命令來檢查當前的配置情況：

$ git config --global user.email # check current global config
$ git config user.email # check current local config

修改配置好的郵箱地址：

$ git config --global user.email name@example.com # change global config
$ git config user.email name@example.com # change local config

步驟 1: 貢獻者證書協(xié)議

在你提交第一個代碼變更到 Go 語言項目之前，你必須先簽署下面兩種證書協(xié)議的其中之一。最后的代碼版權(quán)歸屬于誰，將決定你應該簽署哪一種協(xié)議。

• 如果你個人是版權(quán)持有方，你就需要同意 individual contributor license agreement 并簽署，這個步驟可以在線上完成。
• 如果企業(yè)/組織是版權(quán)持有方，那么企業(yè)/組織就需要同意 corporate contributor license agreement 并簽署。

你可以在 Google Developers Contributor License Agreements 網(wǎng)站上檢查當前已簽署的協(xié)議以及再簽署新的協(xié)議。如果你代碼的版權(quán)持有方之前已經(jīng)在其他的 Google 開源項目上簽署過這些協(xié)議了，那么就不需要再重復簽署了。

如果你代碼的版權(quán)持有方更改了--例如，如果你開始代表新的公司來貢獻代碼--請發(fā)送郵件到 golang-dev 郵件組。這樣我們可以知悉情況，接著準備一份新的協(xié)議文件以及更新作者文件。

步驟 2: 配置 git 認證信息

Go 語言的主倉庫位于 go.googlesource.com，這是一個 Google 自建的 Git 服務器。Web 服務器上的認證信息是通過你的 Google 帳戶生成的，不過你還是需要在你的個人電腦上安裝配置 git 來訪問它。按照以下的步驟進行：

訪問 go.googlesource.com 然后點擊頁面右上角菜單條上的 "Generate Password" 按鈕。接著你會被重定向到 accounts.google.com 去登陸。

登陸之后，你會被引導到一個標題為 "Configure Git" 的網(wǎng)頁。這個網(wǎng)頁包含了一段個性化的腳本代碼，運行這個腳本之后會自動生成身份認證的密鑰并配置到 Git 里面去。這個密鑰是和另一個在遠端 Server 生成并存儲的密鑰成對的，類似于 SSH 密鑰對的工作原理。

復制這段腳本并在你的個人電腦上的終端運行一下，你的密鑰認證 token 就會被保存到一個 .gitcookies 的文件里。如果你使用的是 Windows 電腦，那你應該復制并運行黃色方格里的腳本，而不是下面那個通用的腳本。

步驟 3: 創(chuàng)建一個 Gerrit 賬號

Gerrit 是 Go 語言團隊所使用的一個開源工具，用來進行討論和代碼評審。

要注冊一個你自己的 Gerrit 賬號，訪問 go-review.googlesource.com/login/ 然后使用你上面的 Google 賬號登陸一次，然后就自動注冊成功了。

步驟 4: 安裝 git-codereview 命令行工具

無論是誰，提交到 Go 語言源碼的代碼變更在被接受合并之前，必須要經(jīng)過代碼評審。Go 官方提供了一個叫 git-codereview 的定制化 git 命令行工具，它可以簡化與 Gerrit 的交互流程。

運行下面的命令安裝 git-codereview 命令行工具：

$ go get -u golang.org/x/review/git-codereview

確保 git-codereview 被正確安裝到你的終端路徑里，這樣 git 命令才可以找到它，檢查一下：

git codereview help

正確打印出幫助信息，而且沒有任何錯誤。如果發(fā)現(xiàn)有錯誤，確保環(huán)境變量 $PATH里有$GOPATH/bin這個值。

在 Windows 系統(tǒng)上，當使用 git-bash 的時候你必須確保 git-codereview.exe 已經(jīng)存在于你的 git exec-path 上了?？梢赃\行 git --exec-path 來找到正確的位置然后創(chuàng)建一個軟鏈接指向它或者直接從$GOPATH/bin目錄下拷貝這個可執(zhí)行文件到 exec-path。

貢獻代碼之前

Go 語言項目歡迎提交代碼補丁，但是為了確保很好地進行協(xié)調(diào)，你應該在開始提交重大代碼變更之前進行必要的討論。我們建議你把自己的意圖或問題要不先提交到一個新的 Github issue，要不找到一個和你的問題相同或類似的 issue 跟進查看。

檢查 issue 列表

不管你是已經(jīng)明確了要提交什么代碼，還是你正在搜尋一個想法，你都應該先到 issue 列表 搜索一下。所有 Issues ?被已經(jīng)分門別類以及被用來管理 Go 開發(fā)的工作流。

大多數(shù) issues 會被標記上以下眾多的工作流標簽中的其中一個：

• NeedsInvestigation: 該 issue 并不能被完全清晰地解讀，需要更多的分析去找到問題的根源
• NeedsDecision: 該 issue 已經(jīng)在相當程度上被解讀，但是 Go 團隊還沒有得出一個最好的方法去解決它。最好等 Go 團隊得出了最終的結(jié)論之后才開始寫代碼修復它。如果你對解決這個 issue 感興趣，而且這個 issue 已經(jīng)過了很久都沒得出最終結(jié)論，隨時可以在該 issue 下面發(fā)表評論去"催促"維護者。
• NeedsFix: 該 issue 可以被完全清晰地解讀而且可以開始寫代碼修復它。

你可以使用 Github 的搜索功能去搜尋一個 issue 然后搭把手幫忙解決它。例子：

• Issues that need investigation: is:issue is:open label:NeedsInvestigation
• Issues that need a fix: is:issue is:open label:NeedsFix
• Issues that need a fix and have a CL: is:issue is:open label:NeedsFix "golang.org/cl"
• Issues that need a fix and do not have a CL: is:issue is:open label:NeedsFix NOT "golang.org/cl"

新開一個關(guān)于任何新問題的 issue

除了一些很瑣碎的變更之外，所有的代碼貢獻都應該關(guān)聯(lián)到一個已有的 issue。你隨時可以新開一個 issue 來討論你的相關(guān)計劃。這個流程可以讓所有人都能夠參與驗證代碼的設計，同時幫忙減少一些重復的工作，以及確保這個想法是符合這門語言和相關(guān)工具的目標和理念的。還有就是能在真正開始寫代碼之前就檢查這個代碼設計是否合理；代碼評審工具不是用來討論高層次問題的。

在規(guī)劃你的代碼變更工作的時候，請知悉 Go 語言項目遵循的是 6 個月開發(fā)周期。在每一個 6 個月周期的后半部分是長達 3 個月的新功能特性凍結(jié)期：這期間我們只接受 bug 修復和文檔更新相關(guān)的變更。在凍結(jié)期內(nèi)還是可以提交新的變更的，但是這些變更的代碼在凍結(jié)期結(jié)束之前不會被合并入主分支。

那些針對語言、標準庫或者工具的重大變更必須經(jīng)過變更提議流程才能被接受。

敏感性的安全相關(guān)的 issues 只能上報到 security@golang.org 郵箱！

通過 Github 提交一個變更

我們鼓勵那些初次提交代碼并且已經(jīng)相當熟悉 GitHub 工作流的貢獻者通過標準的 Github 工作流給 Go 提交代碼。盡管 Go 的維護者們是使用 Gerrit 來進行代碼評審，但是不用擔心，會有一個叫 Gopherbot 的機器人專門來做把 Github PR 同步到 Gerrit 上的工作。

就像你通常情況下那樣新建一個 pull request，Gopherbot 會創(chuàng)建一個對應的 Gerrit 變更頁面然后把指向該 Gerrit 變更頁面的鏈接發(fā)布在 GitHub PR 里面；所有 Github PR 的更新都會被同步更新到 Gerrit 里。當有人在 Gerrit 的代碼變更頁面里發(fā)表評論的時候，這些評論也會被同步更新回 Github PR 里，因此 PR owner 將會收到一個通知。

需要謹記于心的東西：

• 如果要在 Github PR 里進行代碼更新的話，只需要把你最新的代碼推送到對應的分支；你可以添加更多的 commits、或者做 rebase 和 force-push 操作(這些方式都是可以接受的)。
• 一旦 Github PR 被接受，所有的 commits 將會被合并成一條，而且最終的 commit 信息將由 PR 的標題和描述聯(lián)結(jié)而成。那些單獨的 commit 描述將會被丟棄掉。查看寫好 Commits 信息獲取更多的建議。
• Gopherbot 無法逐字逐句地把代碼評審的信息同步回 Github: 僅僅是(未經(jīng)格式化的)全部評論的內(nèi)容會被同步過去。請記住，你總是可以訪問 Gerrit 去查看更細粒度和格式化的內(nèi)容。

通過 Gerrit 提交一個變更

一般來說，我們基本不可能在 Gerrit 和 Github 之前完整地同步所有信息，至少在現(xiàn)階段來說是這樣，所以我們推薦你去學習一下 Gerrit。這個不同于 Github 卻同樣強大的工具，而且熟悉它能幫助你更好地理解我們的工作流。

概述

這是一個關(guān)于整個流程的概述：

• 步驟 1: 從go.googlesource.com克隆 Go 的源碼下來，然后通過編譯和測試一次確保這份源碼是完整和穩(wěn)定的:

  $ git clone https://go.googlesource.com/go
  $ cd go/src
  $ ./all.bash # compile and test
  

• 步驟 2: 從 master 分支上拉出一條新分支并在這個分支上準備好你的代碼變更。使用 git codereview change來提交代碼變更；這將會在這個分支上新建或者 amend 一條單獨的 commit。

  $ git checkout -b mybranch
  $ [edit files...]
  $ git add [files...]
  $ git codereview change # create commit in the branch
  $ [edit again...]
  $ git add [files...]
  $ git codereview change # amend the existing commit with new changes
  $ [etc.]
  

• 步驟 3: 重跑 all.bash 腳本，測試你的代碼變更。

  $ ./all.bash # recompile and test
  

• 步驟 4: 使用git codereview mail命令發(fā)送你的代碼變更到 Gerrit 進行代碼評審(這個過程并不使用 e-mail，請忽略這個奇葩名字)。

  $ git codereview mail # send changes to Gerrit
  

• 步驟 5: 經(jīng)過一輪代碼評審之后，把你新的代碼變更依附在同一個單獨 commit 上然后再次使用 mail 命令發(fā)送到 Gerrit:

  $ [edit files...]
  $ git add [files...]
  $ git codereview change # update same commit
  $ git codereview mail # send to Gerrit again
  

這個章節(jié)剩下的內(nèi)容將會把上面的步驟進行詳細的講解。

步驟 1: 克隆 Go 語言的源碼

除了你近期安裝的 Go 版本，你還需要有一份從正確的遠程倉庫克隆下來的本地拷貝。你可以克隆 Go 語言源碼到你的本地文件系統(tǒng)上的任意路徑下，除了你的GOPATH環(huán)境變量對應的目錄。從go.googlesource.com克隆下來 (不是從 Github):

$ git clone https://go.googlesource.com/go
$ cd go

步驟 2: 在新分支上準備好代碼變更

每一次代碼變更都必須在一條從 master 拉出來的獨立分支上開發(fā)。你可以使用正常的 git 命令來新建一條分支然后把代碼變更添加到暫存區(qū)：

$ git checkout -b mybranch
$ [edit files...]
$ git add [files...]

使用 git codereview change而不是git commit命令來提交變更。

$ git codereview change
(open $EDITOR)

你可以像往常一樣在你最喜歡的編輯器里編輯 commit 的描述信息。git codereview change命令會自動在靠近底部的地方添加一個唯一的 Change-Id 行。那一行是被 Gerrit 用來匹配歸屬于同一個變更的多次連續(xù)的上傳。不要編輯或者是刪除這一行。一個典型的 Change-Id 一般長的像下面這樣：

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

這個工具還會檢查你是否有使用 go fmt命令對代碼進行格式化，以及你的 commit 信息是否遵循建議的格式。

如果你需要再次編輯這些文件，你可以把新的代碼變更暫存到暫存區(qū)然后重跑git codereview change: 后續(xù)每一次運行都會 amend 到現(xiàn)存的上一條 commit 上，同時保留同一個 Change-Id。

確保在每一條分支上都只存在一個單獨的 commit，如果你不小心添加了多條 commits，你可以使用git rebase來把它們合并成一條。

步驟 3: 測試你的代碼變更

此時，你已經(jīng)寫好并測試好你的代碼了，但是在提交你的代碼去進行代碼評審之前，你還需要對整個目錄樹運行所有的測試來確保你的代碼變更沒有對其他的包或者程序造成影響/破壞：

$ cd go/src
$ ./all.bash

(如果是在 Windows 下構(gòu)建，使用all.bat；還需要在保存 Go 語言源碼樹的目錄下為引導編譯器設置環(huán)境變量 GOROOT_BOOTSTRAP。)

在運行和打印測試輸出一段時間后，這個命令在結(jié)束前打印的最后一行應該是：

ALL TESTS PASSED

你可以使用 make.bash 而不是 all.bash 來構(gòu)建編譯器以及標準庫而不用運行整個測試套件。一旦 go 工具構(gòu)建完成，一個 bin/go 可執(zhí)行程序會被安裝在你前面克隆下來的 Go 語言源碼的根目錄下，然后你可以在那個目錄下直接運行那個程序?？梢圆榭纯焖贉y試你的代碼變更這個章節(jié)。

步驟 4: 提交代碼變更進行代碼評審

一旦代碼變更準備好了而且通過完整的測試了，就可以發(fā)送代碼變更去進行代碼評審了。這個步驟可以通過 mail 子命令完成，當然它并沒有發(fā)送任何郵件；他只是把代碼變更發(fā)送到 Gerrit 上面去了：

git codereview mail

Gerrit 會給你的變更分配一個數(shù)字和 URL，通過 git codereview mail 打印出來，類似于下面的：

remote: New Changes:
remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments

如果有錯誤，查看?mail 命令錯誤大全和故障排除。

如果你的代碼變更關(guān)聯(lián)到一個現(xiàn)存的 Github issue 而且你也已經(jīng)遵循了建議的 commit 信息格式，機器人將會在幾分鐘更新那個 issue：在評論區(qū)添加 Gerrit 變更頁面的鏈接。

步驟 5: 代碼評審之后修正變更

Go 語言的維護者們會在 Gerrit 上對你的代碼進行 review，然后你會收到一堆郵件通知。你可以在 Gerrit 上查看詳情以及發(fā)表評論，如果你更傾向于直接使用郵件回復，也沒問題。

如果你需要在一輪代碼評審之后更新代碼，直接在你之前創(chuàng)建的同一條分支上編輯代碼文件，接著添加這些文件進 Git 暫存區(qū)，最后通過 git codereview change amend 到上一條 commit：

$ git codereview change # amend current commit
(open $EDITOR)
$ git codereview mail # send new changes to Gerrit

要是你不需要更改 commit 描述信息，可以直接在編輯器保存然后退出。記得不要去碰那一行特殊的 Change-Id。

再次確保你在每一條分支上只保留了一個單獨的 commit，如果你不小心添加了多條 commits，你可以使用git rebase來把它們合并成一條。

良好的 commit 信息

Go 語言的 commit 信息遵循一系列特定的慣例，我們將在這一章節(jié)討論。

這是一個良好的 commit 信息的例子：

math: improve Sin, Cos and Tan precision for very large arguments

The existing implementation has poor numerical properties for
large arguments, so use the McGillicutty algorithm to improve
accuracy above 1e10.

The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm

Fixes #159

首行

變更信息的第一行照慣例一般是一短行關(guān)于代碼變更的概述，前綴是此次代碼變更影響的主要的包名。

作為經(jīng)驗之談，這一行是作為 "此次變更對 Go 的 _________ 部分進行了改動" 這一個句子的補全信息，也就是說這一行并不是一個完整的句子，因此并不需要首字母大寫，僅僅只是對于代碼變更的歸納總結(jié)。

緊隨第一行之后的是一個空行。

主干內(nèi)容

描述信息中剩下的內(nèi)容會進行詳盡地闡述以及會提供關(guān)于此次變更的上下文信息，而且還要解釋這個變更具體做了什么。請用完整的句子以及正確的標點符號來表達，就像你在 Go 代碼里的注釋那樣。不要使用 HTML、Markdown 或者任何其他的標記語言。

添加相關(guān)的信息，比如，如果是性能相關(guān)的改動就需要添加對應的壓測數(shù)據(jù)。照慣例會使用 benchstat 工具來對壓測數(shù)據(jù)進行格式化處理，以便寫入變更信息里。

引用 issues

接下來那個特殊的表示法 "Fixes #12345" 把代碼變更關(guān)聯(lián)到了 Go issue tracker 列表里的 issue 12345。當這個代碼變更最終實施之后 (也就是合入主干)，issue tracker 將會自動標記那個 issue 為"已解決"并關(guān)閉它。

如果這個代碼變更只是部分解決了這個 issue 的話，請使用 "Updates #12345"，這樣的話就會在那個 issue 的評論區(qū)里留下一個評論把它鏈接回 Gerrit 上的變更頁面，但是在該代碼變更被實施之后并不會關(guān)閉掉 issue。

如果你是針對一個子倉庫發(fā)送的代碼變更，你必須使用 Github 支持的完全形式的語法來確保這個代碼變更是鏈接到主倉庫的 issue 上去的，而非子倉庫。主倉庫的 issue tracker 會追蹤所有的 issues，正確的格式是 "Fixes golang/go#159"。

代碼評審流程

這個章節(jié)是對代碼評審流程的詳細介紹以及如何在一個變更被發(fā)送之后處理反饋。

常見的新手錯誤

當一個變更被發(fā)送到 Gerrit 之后，通常來說它會在幾天內(nèi)被分門別類。一個維護者將會查看并提供一些初始的評審，對于初次提交代碼貢獻者來說，這些評審通常集中在基本的修飾和常見的錯誤上。

內(nèi)容包括諸如：

• Commit 信息沒有遵循建議的格式
• 沒有鏈接到對應的 Github issue。大部分代碼變更需要鏈接到對應的 Github issue，說明這次變更修復的 bug 或者實現(xiàn)的功能特性，而且在開始這個變更之前，issue 里應該已經(jīng)達成了一致的意見。Gerrit 評審不會討論代碼變更的價值，僅僅是討論它的具體實現(xiàn)。
• 變更如果是在開發(fā)周期的凍結(jié)階段被發(fā)送到 Gerrit 上的，也就是說彼時 Go 代碼樹是不接受一般的變更的，這種情況下，一個維護者可能會在評審代碼時留下一行這樣的評論：R=go.1.12，意思是這個代碼變更將會在下一個開發(fā)窗口期打開 Go 代碼樹的時候再進行評審。如果你知道那不是這個代碼變更應該被評審的正確的時間范圍，你可以自己加上這樣的評論：R=go1.XX 來更正。

Trybots

在第一次看過你的代碼變更之后，維護者會啟動一些 trybots，這是一個會在不同的 CPU 架構(gòu)的機器上運行完整測試套件的服務器集群。大部分 trybots 會在幾分鐘內(nèi)執(zhí)行完成，之后會有一個可以查看具體結(jié)果的鏈接出現(xiàn)在 Gerrit 變更頁面上。

如果 trybot 最后執(zhí)行失敗了，點擊鏈接然后查看完整的日志，看看是在哪個平臺上測試失敗了。盡量嘗試去弄明白失敗的原因，然后更新你的代碼去修復它，最后重新上傳你的新代碼。維護者會重新啟動一個新的 trybot 再跑一遍，看看問題是不是已經(jīng)解決了。

有時候，Go 代碼樹會在某些平臺上有長達數(shù)小時的執(zhí)行失敗；如果 trybot 上報的失敗的問題看起來和你的這次代碼變更無關(guān)的話，到構(gòu)建面板上去查看近期內(nèi)的其他 commits 在相同的平臺上是不是有出現(xiàn)過這種一樣的失敗。如果有的話，你就在 Gerrit 變更頁面的評論區(qū)里說明一下這個失敗和你的代碼變更無關(guān)，以此讓維護者知悉這種情況。

評審

Go 語言社區(qū)非常重視全面的評審。你要把每一條評審的評論的當成一張罰單：你必須通過某種方式把它"關(guān)掉"，或者是你把評論里建議的修改實現(xiàn)一下，或者是你說服維護者那部分不需要修改。

在你更新了你的代碼之后，過一遍評審頁面的所有評論，確保你已經(jīng)全部回復了。你可以點擊 "Done" 按鈕回復，這表示你已經(jīng)實現(xiàn)了評審人建議的修改，否則的話，點擊 "Reply" 按鈕然后解釋一下你為什么還沒修改、或者是你已經(jīng)做了其他地方的修改并覆蓋了這一部分。

一般來說，代碼評審里會經(jīng)歷多輪的評審，期間會有一個或者多個評審人不斷地發(fā)表新的代碼審查評論然后等待提交者修改更新代碼之后繼續(xù)評審，這是很正常的。甚至一些經(jīng)驗老到的代碼貢獻者也會經(jīng)歷這種循環(huán)，所以不要因此而被打擊到。

投票規(guī)則

在評審人們差不多要得出結(jié)論之時，他們會對你的此次代碼變更進行"投票"。Gerrit 的投票系統(tǒng)包含了一個在[-2, 2]區(qū)間的整數(shù)：

• +2: 同意此次代碼變更被合入到主分支。只有 Go 語言的維護者們才有權(quán)限投 +2 的票。
• +1: 這個代碼變更看起來沒什么問題，不過要么是因為評審人還要求對代碼做一些小的改動、要么是因為該評審人不是一個維護者而無法直接批準這個變更，但是該評審人支持批準這個變更。
• -1: 這個代碼變更并不是很合理但可能有機會做進一步的修改。如果你得到了一個 -1 票，那一定會有一個明確的解釋告訴你為什么。
• -2: 一個維護者否決了這個代碼變更并且不同意合入主干。同樣的，會有一個明確的解釋來說明原因。

提交一個核準的變更

在一個代碼變更被投了一個 +2 票之后，投下這票的核準人將會使用 Gerrit 的用戶界面來將代碼合并入主干，這個操作被稱為"提交變更"。

之所以把核準和提交拆分成兩步，是因為有些時候維護者們可能并不想把剛剛批準的代碼變更立刻合入主干，比如，彼時可能正處于 Go 代碼樹的暫時凍結(jié)期。

提交一個變更將會把代碼合入主倉庫，代碼變更的描述信息里會包含一個指向?qū)a評審頁面的鏈接，而具體代碼評審頁面處也會更新一個鏈接指向倉庫里的此次代碼變更 commit。把代碼變更合入主干時使用的是 Git 的 "Cherry Pick" 命令，因此在主倉庫里的關(guān)于此次代碼變更的 commit 哈希 ID 會被這個提交操作更改。

如果你的變更已經(jīng)被批準了好幾天了，但是一直沒有被提交到主倉庫，你可以在 Gerrit 寫個評論要求合入。

更多信息

除了這里的信息，Go 語言社區(qū)還維護了一個代碼評審的 wiki 頁面。隨時歡迎你在學習相關(guān)的評審流程之時為這個頁面貢獻、補充新內(nèi)容。

其他主題

這個章節(jié)收集了一些除了 issue/edit/code review/submit 流程之外的注解信息。

版權(quán)標頭

Go 語言倉庫里的文件不會保存一份作者列表，既是為了避免雜亂也是為了避免需要實時更新這份列表。相反的，你的名字將會出現(xiàn)在變更日志和貢獻者文件里，也可能會出現(xiàn)在作者文件里。這些文件是定期從 commit 日志上自動生成的。作者文件定義了哪些人是 “Go語言作者” - 版權(quán)持有者。

如果你在提交變更的時候有新添加的文件，那么應該使用標準的版權(quán)頭：

// Copyright 2020 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

(如果你此刻是在 2021 年或者往后的時間閱讀這份文檔，請使用你當前的年份。)倉庫里的文件版權(quán)生效于被添加進去的當年，不要在你變更的文件里更改版權(quán)信息里的年份。

mail 命令錯誤大全和故障排除

git codereview mail命令失敗的最常見原因是因為你的郵件地址和你在注冊流程中使用的郵件地址不匹配。

如果你看到這樣的輸出信息：

remote: Processing changes: refs: 1, done
remote:
remote: ERROR: In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
remote: ERROR: author email address XXXXXXXXXXXXXXXXXXX
remote: ERROR: does not match your user account.

你需要在這個倉庫下把 Git 用戶郵箱配置為你一開始注冊好的那個郵箱。更正郵箱地址以確保不會再發(fā)生這個錯誤：

$ git config user.email email@address.com

然后通過以下命令修改你的 commit 信息，更正里面的用戶名和郵箱：

$ git commit --amend --author="Author Name "

最后運行一下的命令再重試一次：

$ git codereview mail

快速測試你的代碼變更

如果每一次單獨的代碼變更都對整個代碼樹運行 all.bash 腳本的話太費勁了，盡管我們極力建議你在發(fā)送代碼變更之前跑一下這個腳本，然而在開發(fā)的期間你可能只想要編譯和測試那些你涉及到的包。

• 通常來說，你可以運行 make.bash 而不是 all.bash 來只構(gòu)建 Go 工具鏈，而不需要運行整個測試套件?；蛘吣憧梢赃\行 run.bash 來運行整個測試套件而不構(gòu)建 Go 工具鏈。你可以把 all.bash 看成是依次執(zhí)行 make.bash和 run.bash。

• 在這個章節(jié)，我們會把你存放 Go 語言倉庫的目錄稱為 $GODIR。make.bash 腳本構(gòu)建的 go 工具會被安裝到 $GODIR/bin/go 然后你就可以調(diào)用它來測試你的代碼了。例如，如果你修改了編譯器而且你想要測試看看會對你自己項目里的測試套件造成怎樣的影響，直接用它運行 go test：

  $ cd
  $ $GODIR/bin/go test

• 如果你正在修改標準庫，你可能不需要重新構(gòu)建編譯器：你可以直接在你正在修改的包里跑一下測試代碼就可以了。你可以使用平時用的 Go 版本或者從克隆下來的源碼構(gòu)建而成的編譯器(有時候這個是必須的因為你正在修改的標準庫代碼可能會需要一個比你已經(jīng)安裝的穩(wěn)定版更新版本的編譯器)來做這件事。

  $ cd $GODIR/src/hash/sha1
  $ [make changes...]
  $ $GODIR/bin/go test .
  

• 如果你正在修改編譯器本身，你可以直接重新編譯 編譯 工具(這是一個使用 go build 命令編譯每一個單獨的包之時會調(diào)用到的一個內(nèi)部的二進制文件)。完成之后，你會想要編譯或者運行一些代碼來測試一下：

  $ cd $GODIR/src
  $ [make changes...]
  $ $GODIR/bin/go install cmd/compile
  $ $GODIR/bin/go build [something...] # test the new compiler
  $ $GODIR/bin/go run [something...] # test the new compiler
  $ $GODIR/bin/go test [something...] # test the new compiler
  

  同樣的操作可以應用到 Go 工具鏈里的其他內(nèi)部工具，像是 asm，cover，link 等等。直接重新編譯然后使用 go install cmd/ 命令安裝，最后使用構(gòu)建出來的 Go 二進制文件測試一下。

• 除了標準的逐包測試，在 $GODIR/test 目錄下有一個頂級的測試套件，里面包含了多種黑盒和回歸測試。這個測試套件是包含在 all.bash 腳本里運行的，不過你也可以手動運行它：

  $ cd $GODIR/test
  $ $GODIR/bin/go run run.go
  

向子倉庫提交貢獻 (golang.org/x/...)

如果你正在向一個子倉庫提交貢獻，你需要使用 go get 來獲取對應的 Go 包。例如，如果要向 golang.org/x/oauth2 包貢獻代碼，你可以通過運行以下的命令來獲取代碼：

$ go get -d golang.org/x/oauth2/...

緊接著，進入到包的源目錄($GOPATH/src/golang.org/x/oauth2)，然后按照正常的代碼貢獻流程走就行了。

指定一個評審人/抄送其他人

除非有明確的說明，比如在你提交代碼變更之前的討論中，否則的話最好不要自己指定評審人。所有的代碼變更都會自動抄送給 golang-codereviews@googlegroups.com 郵件組。如果這是你的第一次提交代碼變更，在它出現(xiàn)在郵件列表之前可能會有一個審核延遲，主要是為了過濾垃圾郵件。

你可以指定一個評審人或者使用 -r/-cc 選項抄送有關(guān)各方。這兩種方式都接受逗號分隔的郵件地址列表：

$ git codereview mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com

同步你的客戶端

在你做代碼變更期間，可能有其他人的變更已經(jīng)先你一步被提交到主倉庫里，那么為了保持你的本地分支更新，運行：

git codereview sync

(這個命令背后運行的是 git pull -r.)

其他人評審代碼

評審人作為評審流程的一部分可以直接提交代碼到你的變更里(就像是在 Github 工作流里有其他人把 commits 依附到你的 PR 上了)。你可以導入這些他人提交的變更到你的本地 Git 分支上。在 Gerrit 的評審頁面，點擊右上角的 "Download ▼" 鏈接，復制 "Checkout" 命令然后在你的本地 Git 倉庫下運行它。這個命令類似如下的格式：

$ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD

如果要撤銷，切換回你之前在開發(fā)的那個分支即可。

設置 git 別名

git codereview 相關(guān)的命令可以直接在終端鍵入對應的選項運行，例如：

$ git codereview sync

不過給 git codereview 子命令命令設置別名會更方便使用，上面的命令可以替換成：

$ git sync

git codereview 的子命令的名字是排除了 Git 本身的命令關(guān)鍵字而挑選出來的，所以不用擔心設置了這些別名會和 Git 本身的命令沖突。要設置這些別名，復制下面的文本到你的 Git 配置文件里(通常是在 home 路徑下的 .gitconfig 文件)：

[alias]
change = codereview change
gofmt = codereview gofmt
mail = codereview mail
pending = codereview pending
submit = codereview submit
sync = codereview sync

發(fā)送多個依賴的變更

老司機用戶可能會想要把相關(guān)的 commits 疊加到一個單獨的分支上。Gerrit 允許多個代碼變更之間相互依賴，形成這樣的依賴鏈。每一個變更需要被單獨地核準和提交，但是依賴對于評審人來說是可見的。

要發(fā)送一組依賴的代碼更改，請將每個變更作為不同的 commit 保存在同一分支下，然后運行：

$ git codereview mail HEAD

要確保顯示地指定 HEAD，不過這在單個變更的場景里通常是不需要指定的。

英文原文地址

https://golang.org/doc/contribute.html

References

[1]?代碼評審:?https://github.com/golang/go/wiki/CodeReview[2]?Contributing to gccgo:?https://golang.org/doc/gccgo_contribute.html[3]?簽署以及提交:?https://cla.developers.google.com/clas[4]?go.googlesource.com:?https://go.googlesource.com/[5]?這個頁面:?https://go-review.googlesource.com/login/[6]?貢獻代碼之前:?#貢獻代碼之前[7]?創(chuàng)建一個綁定了外部郵箱的 Google 賬號:?https://accounts.google.com/SignUpWithoutGmail[8]?individual contributor license agreement:?https://developers.google.com/open-source/cla/individual[9]?corporate contributor license agreement:?https://developers.google.com/open-source/cla/corporate[10]?Google Developers Contributor License Agreements:?https://cla.developers.google.com/clas?pli=1&authuser=1[11]?golang-dev?郵件組:?mailto:golang-dev@googlegroups.com[12]?go.googlesource.com:?https://go.googlesource.com/[13]?go.googlesource.com:?https://go.googlesource.com/[14]?go-review.googlesource.com/login/:?https://go-review.googlesource.com/login/[15]?issue 列表:?https://github.com/golang/go/issues[16]?is:issue is:open label:NeedsInvestigation:?https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation[17]?is:issue is:open label:NeedsFix:?https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix[18]?is:issue is:open label:NeedsFix "golang.org/cl":?https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+"golang.org%2Fcl"[19]?is:issue is:open label:NeedsFix NOT "golang.org/cl":?https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+"golang.org%2Fcl"[20]?6 個月開發(fā)周期:?https://golang.org/wiki/Go-Release-Cycle[21]?變更提議流程:?https://golang.org/s/proposal-process[22]?security@golang.org:?mailto:security@golang.org[23]?GitHub 工作流:?https://guides.github.com/introduction/flow/[24]?寫好 Commits 信息:?#良好的-commit-信息[25]?建議的格式:?#良好的-commit-信息[26]?把它們合并成一條:?https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github[27]?寫好并測試好你的代碼:?https://golang.org/doc/code.html[28]?快速測試你的代碼變更:?#快速測試你的代碼變更[29]?mail 命令錯誤大全和故障排除:?#mail-命令錯誤大全和故障排除[30]?建議的 commit 信息格式:?#良好的-commit-信息[31]?使用郵件:?https://gerrit-review.googlesource.com/Documentation/intro-user.html#reply-by-email[32]?把它們合并成一條:?https://stackoverflow.com/questions/31668794/squash-all-your-commits-in-one-before-a-pull-request-in-github[33]?benchstat:?https://godoc.org/golang.org/x/perf/cmd/benchstat[34]?Go issue tracker:?https://golang.org/issue/12345[35]?建議的格式:?#良好的-commit-信息[36]?構(gòu)建面板:?https://build.golang.org/[37]?代碼評審:?https://golang.org/wiki/CodeReview[38]?變更日志:?https://golang.org/change[39]?貢獻者:?https://golang.org/CONTRIBUTORS[40]?作者:?https://golang.org/AUTHORS[41]?作者:?https://golang.org/AUTHORS[42]?注冊流程:?#步驟-0-選擇一個-google-賬號[43]?golang-codereviews@googlegroups.com:?https://groups.google.com/group/golang-codereviews

總結(jié)

以上是生活随笔為你收集整理的golang中文文档_【译】Go 语言源码贡献官方指导文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。