【譯】Go 語言項目源碼貢獻官方指導文檔

時間 2020-06-15

標籤語言項目源碼貢獻官方指導文檔简体版

原文原文鏈接

之前給 Go 語言項目源碼提交過一些 commits，期間閱讀他們的官方指導文檔的時候以爲這篇指導文檔能夠做爲絕佳的關於大型軟件項目的規範管理的參考，由於最近又提交了幾個 commits，就又把這篇文檔再看了一遍，有感於 Go 團隊在項目管理和工程實踐上的一些寶貴經驗，就把文檔翻譯成了中文；一來爲了更加深刻地理解 Go 語言團隊的項目工程最佳實踐，二來則是爲了給其餘有意給 Go 語言源碼提交貢獻的開發者提供一點參考。

導言

Go 語言項目歡迎全部的代碼貢獻者。html

這是一份指導你完成向 Go 語言項目貢獻代碼整個流程的文檔，會略微跟其餘開源項目所使用的指導文檔有所不一樣。咱們假設閱讀者已經對 Git 和 Go 有基本的理解以及具有相關的基礎知識。前端

除了這裏所介紹的信息，Go 語言社區也維護了一份關於代碼評審的 wiki 頁面。在你學習評審流程期間，歡迎隨時給這份 wiki 貢獻、補充新內容。git

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

成爲一個代碼貢獻者

概述

第一步須要註冊成爲一個 Go contributor 以及配置你的環境。這裏有一份包含了所需步驟的清單：golang

步驟 0: 準備好一個你將用來給 Go 語言貢獻代碼的 Google 帳號。在後面全部的步驟中都要使用這個帳號，還有確保你的 git 已經正確配置了這個帳號的郵箱地址，以便後續提交 commits。
步驟 1: 簽署以及提交一個 CLA（貢獻者證書協議）。
步驟 2: 給 Go Git 倉庫配置好權限憑證。訪問 go.googlesource.com，點擊右上角的齒輪圖標，接着點擊 "Obtain password"，而後跟着指引操做便可。
步驟 3: 在這個頁面註冊一個 Gerrit 帳號，它是 Go 語言團隊使用的代碼評審工具。CLA 的申請和 Gerrit 的註冊只須要在你的帳號上作一次就能夠了
步驟 4: 運行 go get -u golang.org/x/review/git-codereview 命令安裝 git-codereview 工具。

若是你圖省事的話，能夠直接用自動化工具幫你完成上面的所有步驟，只需運行：shell

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

這個章節的後面部分將會更加詳盡地闡述上面的每個步驟。若是你已經完成上面的全部步驟（無論是手動仍是經過自動化工具），能夠直接跳到貢獻代碼以前部分。安全

步驟 0: 選擇一個 Google 帳號

每個提交到 Go 語言的代碼貢獻都是經過一個綁定了特定郵箱地址的 Google 帳號來完成的。請確保你在整個流程中自始至終使用的都是同一個帳號，固然，後續你提交的全部代碼貢獻也是如此。你可能須要想好使用哪種郵箱，我的的仍是企業的。郵箱類型的選擇將決定誰擁有你編寫和提交的代碼的版權。在決定使用哪一個帳戶以前，你大概要和你的僱主商議一下。bash

Google 帳號能夠是 Gmail 郵箱帳號、G Suite 組織帳號，或者是那些綁定了外部郵箱的帳號。例如，若是你想要使用一個已存在且並不屬於 G Suite 的企業郵箱，你能夠建立一個綁定了外部郵箱的 Google 帳號。服務器

你還須要確保你的 Git 工具已經正確配置好你以前選定的郵箱地址，用來提交代碼。你能夠經過 Git 命令來進行全局配置(全部項目都將默認使用這個配置)或者只進行本地配置(只指定某個特定的項目使用)。能夠經過如下的命令來檢查當前的配置狀況：cookie

$ 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: 貢獻者證書協議

在你發送第一個代碼變動到 Go 語言項目(進行評審)以前，你必須先簽署下面兩種證書協議的其中之一。最後的代碼版權歸屬於誰，將決定你應該簽署哪種協議。

若是你我的是版權持有方，你就須要贊成 individual contributor license agreement 並簽署，這個步驟能夠在線上完成。
若是企業/組織是版權持有方，那麼企業/組織就須要贊成 corporate contributor license agreement 並簽署。

你能夠在 Google Developers Contributor License Agreements 網站上檢查當前已簽署的協議以及再簽署新的協議。若是你代碼的版權持有方以前已經在其餘的 Google 開源項目上籤署過這些協議了，那麼就不須要再重複簽署了。

若是你代碼的版權持有方更改了--例如，若是你開始表明新的公司來貢獻代碼--請發送郵件到 golang-dev 郵件組。這樣咱們能夠知悉狀況，接着準備一份新的協議文件以及更新 做者 文件。

步驟 2: 配置 Git 認證信息

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

訪問 go.googlesource.com 而後點擊頁面右上角菜單條上的 "Generate Password" 按鈕。接着你會被重定向到 accounts.google.com 去登錄。
登錄以後，你會被引導到一個標題爲 "Configure Git" 的網頁。這個網頁包含了一段個性化的腳本代碼，運行這個腳本以後會自動生成身份認證的密鑰並配置到 Git 裏面去。這個密鑰是和另外一個在遠端 Server 生成並存儲的密鑰成對的，相似於 SSH 密鑰對的工做原理。
複製這段腳本並在你的我的電腦上的終端運行一下，你的密鑰認證 token 就會被保存到一個 .gitcookies 的文件裏。若是你使用的是 Windows 電腦，那你應該複製並運行黃色方格里的腳本，而不是下面那個通用的腳本。

步驟 3: 建立一個 Gerrit 帳號

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

要註冊一個你本身的 Gerrit 帳號，訪問 go-review.googlesource.com/login/ 而後使用你上面的 Google 帳號登錄一次，而後就自動註冊成功了。

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

不管是誰，提交到 Go 語言源碼的代碼變動在被接受合併以前，必需要通過代碼評審。Go 官方提供了一個叫 git-codereview 的定製化 git 命令行工具，它能夠簡化與 Gerrit 的交互流程。

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

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

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

git codereview help

正確打印出幫助信息，並且沒有任何錯誤。若是發現有錯誤，確保環境變量 $PATH 裏有 $GOPATH/bin 這個值。

在 Windows 系統上，當使用 git-bash 的時候你必須確保 git-codereview.exe 已經存在於你的 git exec-path 上了。能夠運行 git --exec-path 來找到正確的位置而後建立一個軟連接指向它或者直接從 $GOPATH/bin 目錄下拷貝這個可執行文件到 exec-path。

貢獻代碼以前

Go 語言項目歡迎提交代碼補丁，可是爲了確保很好地進行協調，你應該在開始提交重大代碼變動以前進行必要的討論。咱們建議你把本身的意圖或問題要不先提交到一個新的 GitHub issue，要不找到一個和你的問題相同或相似的 issue 跟進查看。

檢查 issue 列表

無論你是已經明確了要提交什麼代碼，仍是你正在搜尋一個想法，你都應該先到 issue 列表看一下。全部 Issues 已經被分門別類以及被用來管理 Go 開發的工做流。

大多數 issues 會被標記上如下衆多的工做流標籤中的其中一個：

NeedsInvestigation: 該 issue 並不能被徹底清晰地解讀，須要更多的分析去找到問題的根源
NeedsDecision: 該 issue 已經在至關程度上被解讀，可是 Go 團隊尚未得出一個最好的方法去解決它。最好等 Go 團隊得出了最終的結論以後纔開始寫代碼修復它。若是你對解決這個 issue 感興趣，並且這個 issue 已通過了好久都沒得出最終結論，隨時能夠在該 issue 下面發表評論去"催促"維護者。
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"

新開一個關於任何新問題的 issue

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

在規劃你的代碼變動工做的時候，請知悉 Go 語言項目遵循的是 6 個月開發週期。在每個 6 個月週期的後半部分是長達 3 個月的新功能特性凍結期：這期間咱們只接受 bug 修復和文檔更新相關的變動。在凍結期內仍是能夠提交新的變動的，可是這些變動的代碼在凍結期結束以前不會被合併入主分支。

那些針對語言、標準庫或者工具的重大變動必須通過變動提議流程才能被接受。

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

經過 GitHub 提交一個變動

咱們鼓勵那些初次提交代碼而且已經至關熟悉 GitHub 工做流的貢獻者經過標準的 GitHub 工做流給 Go 提交代碼。儘管 Go 的維護者們是使用 Gerrit 來進行代碼評審，可是不用擔憂，會有一個叫 Gopherbot 的機器人專門把 GitHub PR 同步到 Gerrit 上。

就像你以往那樣新建一個 pull request，Gopherbot 會建立一個對應的 Gerrit 變動頁面而後把指向該 Gerrit 變動頁面的連接發佈在 GitHub PR 裏面；全部 GitHub PR 的更新都會被同步更新到 Gerrit 裏。當有人在 Gerrit 的代碼變動頁面裏發表評論的時候，這些評論也會被同步更新回 GitHub PR 裏，所以 PR owner 將會收到一個通知。

須要謹記於心的東西：

若是要在 GitHub PR 裏進行代碼更新的話，只須要把你最新的代碼推送到對應的分支；你能夠添加更多的 commits、或者作 rebase 和 force-push 操做（不管哪一種方式都是能夠接受的）。
一旦 GitHub PR 被接受，全部的 commits 將會被合併成一條，並且最終的 commit 信息將由 PR 的標題和描述聯結而成。那些單獨的 commit 描述將會被丟棄掉。查看寫好 Commits 信息獲取更多的建議。
Gopherbot 沒法逐字逐句地把代碼評審的信息同步回 Github: 僅僅是(未經格式化的)所有評論的內容會被同步過去。請記住，你老是能夠訪問 Gerrit 去查看更細粒度和格式化的內容。

經過 Gerrit 提交一個變動

通常來講，咱們基本不可能在 Gerrit 和 GitHub 之間完整地同步全部信息，至少在現階段來講是這樣，因此咱們推薦你去學習一下 Gerrit。它是不一樣於 GitHub 卻一樣強大的工具，並且熟悉它能幫助你更好地理解咱們的工做流。

概述

這是一個關於整個流程的概述：

步驟 1: 從 go.googlesource.com 克隆 Go 的源碼下來，而後經過編譯和測試一次確保這份源碼是完整和穩定的：
```
$ 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 命令發送你的代碼變動到 Gerrit 進行代碼評審(這個過程並不使用 e-mail，請忽略這個奇葩名字)。
```
$ git codereview mail     # send changes to Gerrit
```
步驟 5: 通過一輪代碼評審以後，把你新的代碼變動依附在同一個單獨 commit 上而後再次使用 mail 命令發送到 Gerrit:
```
$ [edit files...]
$ git add [files...]
$ git codereview change   # update same commit
$ git codereview mail     # send to Gerrit again
```

這個章節剩下的內容將會把上面的步驟進行詳細的講解。

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

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

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

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

每一次代碼變動都必須在一條從 master 拉出來的獨立分支上開發。你可使用正常的 git 命令來新建一條分支而後把代碼變動添加到暫存區：

$ 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 用來匹配歸屬於同一個變動的屢次連續的上傳。不要編輯或者是刪除這一行。一個典型的 Change-Id 通常長的像下面這樣：

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

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

若是你須要再次編輯這些文件，你能夠把新的代碼變動暫存到暫存區而後重跑 git codereview change : 後續每一次運行都會 amend 到現存的上一條 commit 上，同時保留同一個 Change-Id。

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

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

此時，你已經寫好並測試好你的代碼了，可是在提交你的代碼去進行代碼評審以前，你還須要對整個目錄樹運行全部的測試來確保你的代碼變動沒有對其餘的包或者程序形成影響/破壞：

$ cd go/src
$ ./all.bash

(若是是在 Windows 下構建，使用 all.bat ；還須要在保存 Go 語言源碼樹的目錄下爲引導編譯器設置環境變量 GOROOT_BOOTSTRAP。)

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

ALL TESTS PASSED

你可使用 make.bash 而不是 all.bash 來構建編譯器以及標準庫而不用運行整個測試套件。一旦 go 工具構建完成，一個 bin/go 可執行程序會被安裝在你前面克隆下來的 Go 語言源碼的根目錄下，而後你能夠在那個目錄下直接運行那個程序。能夠查看快速測試你的代碼變動這個章節。

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

一旦代碼變動準備好了並且經過完整的測試了，就能夠發送代碼變動去進行代碼評審了。這個步驟能夠經過 mail 子命令完成，固然它並無發送任何郵件；只是把代碼變動發送到 Gerrit 上面去了：

git codereview mail

Gerrit 會給你的變動分配一個數字和 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 命令錯誤大全和故障排除。

若是你的代碼變動關聯到一個現存的 GitHub issue 並且你也已經遵循了建議的 commit 信息格式，機器人將會在幾分鐘更新那個 issue：在評論區添加 Gerrit 變動頁面的連接。

步驟 5: 代碼評審以後修正變動

Go 語言的維護者們會在 Gerrit 上對你的代碼進行 review，而後你會收到一堆郵件通知。你能夠在 Gerrit 上查看詳情以及發表評論，若是你更傾向於直接使用郵件回覆，也沒問題。

若是你須要在一輪代碼評審以後更新代碼，直接在你以前建立的同一條分支上編輯代碼文件，接着添加這些文件進 Git 暫存區，最後經過 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 信息遵循一系列特定的慣例，咱們將在這一章節討論。

這是一個良好的 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

首行

變動信息的第一行照慣例通常是一短行關於代碼變動的概述，前綴是這次代碼變動影響的主要的包名。

做爲經驗之談，這一行是做爲 "這次變動對 Go 的 _ 部分進行了改動" 這一個句子的補全信息，也就是說這一行並非一個完整的句子，所以並不須要首字母大寫，僅僅只是對於代碼變動的概括總結。

緊隨第一行以後的是一個空行。

主幹內容

描述信息中剩下的內容會進行詳盡地闡述以及會提供關於這次變動的上下文信息，並且還要解釋這個變動具體作了什麼。請用完整的句子以及正確的標點符號來表達，就像你在 Go 代碼裏的註釋那樣。不要使用 HTML、Markdown 或者任何其餘的標記語言。

添加相關的信息，好比，若是是性能相關的改動就須要添加對應的壓測數據。照慣例會使用 benchstat 工具來對壓測數據進行格式化處理，以便寫入變動信息裏。

引用 issues

接下來那個特殊的表示法 "Fixes #12345" 把代碼變動關聯到了 Go issue tracker 列表裏的 issue 12345。當這個代碼變動最終實施以後 (也就是合入主幹)，issue tracker 將會自動標記那個 issue 爲"已解決"並關閉它。

若是這個代碼變動只是部分解決了這個 issue 的話，請使用 "Updates #12345"，這樣的話就會在那個 issue 的評論區裏留下一個評論把它連接回 Gerrit 上的變動頁面，可是在該代碼變動被實施以後並不會關閉掉 issue。

若是你是針對一個子倉庫發送的代碼變動，你必須使用 GitHub 支持的徹底形式的語法來確保這個代碼變動是連接到主倉庫的 issue 上去的，而非子倉庫。主倉庫的 issue tracker 會追蹤全部的 issues，正確的格式是 "Fixes golang/go#159"。

代碼評審流程

這個章節是對代碼評審流程的詳細介紹以及如何在一個變動被髮送以後處理反饋。

常見的新手錯誤

當一個變動被髮送到 Gerrit 以後，一般來講它會在幾天內被分門別類。接着一個維護者將會查看並提供一些初始的評審，對於初次提交代碼貢獻者來講，這些評審一般集中在基本的修飾和常見的錯誤上。

內容包括諸如：

Commit 信息沒有遵循建議的格式
沒有連接到對應的 GitHub issue。大部分代碼變動須要連接到對應的 GitHub issue，說明此次變動修復的 bug 或者實現的功能特性，並且在開始這個變動以前，issue 裏應該已經達成了一致的意見。Gerrit 評審不會討論代碼變動的價值，僅僅是討論它的具體實現。
變動若是是在開發週期的凍結階段被髮送到 Gerrit 上的，也就是說彼時 Go 代碼樹是不接受通常的變動的，這種狀況下，一個維護者可能會在評審代碼時留下一行這樣的評論：R=go.1.12，意思是這個代碼變動將會在下一個開發窗口期打開 Go 代碼樹的時候再進行評審。若是你知道那不是這個代碼變動應該被評審的正確的時間範圍，你能夠本身加上這樣的評論：R=go1.XX 來更正。

Trybots

在第一次審查完你的代碼變動以後，維護者會啓動一些 trybots，這是一個會在不一樣 CPU 架構的機器上運行完整測試套件的服務器集羣。大部分 trybots 會在幾分鐘內執行完成，以後會有一個能夠查看具體結果的連接出如今 Gerrit 變動頁面上。

若是 trybot 最後執行失敗了，點擊連接而後查看完整的日誌，看看是在哪一個平臺上測試失敗了。儘可能嘗試去弄明白失敗的緣由，而後更新你的代碼去修復它，最後從新上傳你的新代碼。維護者會從新啓動一個新的 trybot 再跑一遍，看看問題是否是已經解決了。

有時候，Go 代碼樹會在某些平臺上有長達數小時的執行失敗；若是 trybot 上報的失敗的問題看起來和你的此次代碼變動無關的話，到構建面板上去查看近期內的其餘 commits 在相同的平臺上是否是有出現過這種同樣的失敗。若是有的話，你就在 Gerrit 變動頁面的評論區裏說明一下這個失敗和你的代碼變動無關，以此讓維護者知悉這種狀況。

評審

Go 語言社區很是重視全面的評審。你要把每一條評審的評論的當成一張罰單：你必須經過某種方式把它"關掉"，或者是你把評論裏評審人建議/要求的改動實現一下，或者是你說服維護者那部分不須要修改。

在你更新了你的代碼以後，過一遍評審頁面的全部評論，確保你已經所有回覆了。你能夠點擊 "Done" 按鈕回覆，這表示你已經實現了評審人建議的修改，不然的話，點擊 "Reply" 按鈕而後解釋一下你爲何還沒修改、或者是你已經作了其餘地方的修改並覆蓋了這一部分。

通常來講，代碼評審裏會經歷多輪的評審，期間會有一個或者多個評審人不斷地發表新的代碼審查評論而後等待提交者修改更新代碼以後繼續評審，這是很正常的。甚至一些經驗老到的代碼貢獻者也會經歷這種循環，因此不要所以而被打擊到。

投票規則

在評審人們差很少要得出結論之時，他們會對你的這次代碼變動進行"投票"。Gerrit 的投票系統包含了一個在[-2, 2]區間的整數：

+2: 贊成這次代碼變動被合入到主分支。只有 Go 語言的維護者們纔有權限投 +2 的票。
+1: 這個代碼變動看起來沒什麼問題，不過要麼是由於評審人還要求對代碼作一些小的改動、要麼是由於該評審人不是一個維護者而沒法直接批准這個變動，可是該評審人支持批准這個變動。
-1: 這個代碼變動並非很合理但可能有機會作進一步的修改。若是你獲得了一個 -1 票，那必定會有一個明確的解釋告訴你爲何。
-2: 一個維護者否決了這個代碼變動而且不一樣意合入主幹。一樣的，會有一個明確的解釋來講明緣由。

提交一個核準的變動

在一個代碼變動被投了一個 +2 票以後，投下這票的核準人將會使用 Gerrit 的用戶界面來將代碼合併入主幹，這個操做被稱爲"提交變動"。

之因此把覈准和提交拆分紅兩步，是由於有些時候維護者們可能並不想把剛剛批准的代碼變動馬上合入主幹，好比，彼時可能正處於 Go 代碼樹的暫時凍結期。

提交一個變動將會把代碼合入主倉庫，代碼變動的描述信息裏會包含一個指向對應代碼評審頁面的連接，而具體代碼評審頁面處也會更新一個連接指向倉庫裏的這次代碼變動 commit。把代碼變動合入主幹時使用的是 Git 的 "Cherry Pick" 命令，所以在主倉庫裏的關於這次代碼變動的 commit 哈希 ID 會被這個提交操做更改。

若是你的變動已經被批准了好幾天了，可是一直沒有被提交到主倉庫，你能夠在 Gerrit 寫個評論要求合入。

其餘主題

這個章節收集了一些除了 issue/edit/code review/submit 流程以外的註解信息。

版權標頭

Go 語言倉庫裏的文件不會保存一份做者列表，既是爲了不雜亂也是爲了不須要實時更新這份列表。相反的，你的名字將會出如今變動日誌和貢獻者文件裏，也可能會出如今做者文件裏。這些文件是按期從 commit 日誌上自動生成的。做者文件定義了哪些人是「Go 語言做者」 - 版權持有者。

若是你在提交變動的時候有新添加的文件，那麼應該使用標準的版權頭：

// 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 年或者日後的時間閱讀這份文檔，請使用你當前的年份。)倉庫裏的文件版權生效於被添加進去的當年，不要在你變動的文件裏更改版權信息裏的年份。

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 用戶郵箱配置爲你一開始註冊好的那個郵箱。更正郵箱地址以確保不會再發生這個錯誤：

$ git config user.email email@address.com

而後經過如下命令修改你的 commit 信息，更正裏面的用戶名和郵箱：

$ git commit --amend --author="Author Name <email@address.com>"

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

$ git codereview mail

快速測試你的代碼變動

若是每一次單獨的代碼變動都對整個代碼樹運行 all.bash 腳本的話太費勁了，儘管咱們極力建議你在發送代碼變動以前跑一下這個腳本，然而在開發的期間你可能只想要編譯和測試那些你涉及到的包。

一般來講，你能夠運行 make.bash 而不是 all.bash 來只構建 Go 工具鏈，而不須要運行整個測試套件。或者你能夠運行 run.bash 來運行整個測試套件而不構建 Go 工具鏈。你能夠把 all.bash 當作是依次執行 make.bash 和 run.bash 。
在這個章節，咱們會把你存放 Go 語言倉庫的目錄稱爲 $GODIR 。 make.bash 腳本構建的 go 工具會被安裝到 $GODIR/bin/go 而後你就能夠調用它來測試你的代碼了。例如，若是你修改了編譯器並且你想要測試看看會對你本身項目裏的測試套件形成怎樣的影響，直接用它運行 go test ：
```
$ cd <MYPROJECTDIR>
$ $GODIR/bin/go test
```
若是你正在修改標準庫，你可能不須要從新構建編譯器：你能夠直接在你正在修改的包裏跑一下測試代碼就能夠了。你可使用平時用的 Go 版本或者從克隆下來的源碼構建而成的編譯器(有時候這個是必須的由於你正在修改的標準庫代碼可能會須要一個比你已經安裝的穩定版更新版本的編譯器)來作這件事。
```
$ cd $GODIR/src/hash/sha1
$ [make changes...]
$ $GODIR/bin/go test .
```
若是你正在修改編譯器自己，你能夠直接從新編譯 編譯 工具（這是一個使用 go build 命令編譯每個單獨的包之時會調用到的一個內部的二進制文件）。完成以後，你會想要編譯或者運行一些代碼來測試一下：
```
$ 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 工具鏈裏的其餘內部工具，像是 asm ， cover ， link 等等。直接從新編譯而後使用 go install cmd/<TOOL> 命令安裝，最後使用構建出來的 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 郵件組。若是這是你的第一次提交代碼變動，在它出如今郵件列表以前可能會有一個審覈延遲，主要是爲了過濾垃圾郵件。

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

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

同步你的客戶端

在你作代碼變動期間，可能有其餘人的變動已經先你一步被提交到主倉庫裏，那麼爲了保持你的本地分支更新，運行：

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

若是要撤銷，切換回你以前在開發的那個分支便可。

設置 Git 別名

git codereview 相關的命令能夠直接在終端鍵入對應的選項運行，例如：

$ git codereview sync

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

$ git sync

git codereview 的子命令的名字是排除了 Git 自己的命令關鍵字而挑選出來的，因此不用擔憂設置了這些別名會和 Git 自己的命令衝突。要設置這些別名，複製下面的文本到你的 Git 配置文件裏（一般是在 home 路徑下的 .gitconfig 文件）：

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