1. 文件
2. 貢獻指南

貢獻指南

Go 專案歡迎所有貢獻者。

本文檔是協助您參與 Go 專案的指南，與其他開放原始碼專案使用的指南稍有不同。我們假設您對 Git 和 Go 有基本了解。

除了這裡提供的資訊外，Go 社群也維護一個 CodeReview wiki 頁面。請隨時在瞭解檢閱流程時加入 wiki。

請注意gccgo 前端存在於其他地方；請參閱 為 gccgo 貢獻。

成為貢獻者

概覽

第一步是註冊成為 Go 貢獻者並設定您的環境。以下是要遵循的必備步驟核對表

• 步驟 0：決定您將用於為 Go 貢獻的單一 Google 帳戶。對所有後續步驟使用該帳戶，並確保git已設定為以該帳戶的電子郵件地址建立提交紀錄。
• 步驟 1：簽署並提交CLA（貢獻者授權合約）。
• 步驟 2：設定 Go Git 儲存庫的驗證認證。請造訪 go.googlesource.com，按一下頁面右上角功能表列上的「產生密碼」，然後遵照指示進行操作。
• 步驟 3：註冊 Go 團隊所使用的程式碼檢閱工具 Gerrit，請 造訪此頁面。CLA 和註冊需要只針對您的帳戶進行一次。
• 步驟 4：安裝 git-codereview，執行 go install golang.org/x/review/git-codereview@latest

如果您願意，有一個自動工具會逐步執行這些步驟。只要執行

$ go install golang.org/x/tools/cmd/go-contrib-init@latest
$ cd /code/to/edit
$ go-contrib-init

本章節的其餘部分說明這些步驟。如果您已完成以上步驟（手動或透過工具），請跳到 在提交程式碼之前。

步驟 0：選擇 Google 帳戶

對 Go 的任何貢獻都是透過具有特定電子郵件地址的 Google 帳戶進行。請務必在整個過程中及所有後續貢獻中使用同一個帳戶。您可能需要決定要使用個人地址或公司地址。選擇會視您撰寫及提交程式碼的著作權所有人而定。您可能需要在決定要使用哪個帳戶之前，先與您的雇主討論這個主題。

Google 帳戶可以是 Gmail 電子郵件帳戶、G Suite 組織帳戶，或與外部電子郵件地址相關聯的帳戶。舉例來說，如果您需要使用現有的非透過 G Suite 管理的公司電子郵件，您可以 建立一個關聯至您現有電子郵件地址 的帳戶。

您還需要確定 Git 工具已設定為使用您選取的電子郵件地址建立 commit。您可以設定 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：貢獻者授權合約

在將您的第一次變更傳送至 Go 專案前，您必須完成以下兩個 CLA 之一。您應該簽署哪一份 CLA 會視您著作權的所有人而定。

• 如果您是著作權人，您需要同意 個人貢獻者授權合約，此合約可以在線上完成。
• 如果您的組織是著作權人，組織需要同意 公司貢獻者授權合約。
  

您可以在 Google Developers 貢獻者授權合約 網站查看您目前已簽署的合約，並簽署新的合約。如果您貢獻的著作權人已在與另一個 Google 開源專案的關聯下完成合約，則不需要再重複完成。

如果你提交程式碼的著作權持有人已變更—例如，你開始代表新公司發布程式碼—請將郵件寄送至golang-dev 郵件串流。這樣我們就可以知道這個情況，並確保已完成適當的合約。

第 2 步：設定 git 驗證

主要的 Go 儲存庫位於 go.googlesource.com，這是 Google 所架設的 Git 伺服器。透過你的 Google 帳戶在網路伺服器上驗證，但你還需要設定你電腦上的 git 才能存取。請執行下列步驟

1. 瀏覽go.googlesource.com，並按一下頁面右上方功能表列中的「產生密碼」。你會被導向 accounts.google.com 來登入。
2. 登入後，你會被帶往標題為「設定 Git」的頁面。此頁面包含一個個人化的指令碼，在本地執行時會設定 Git 以持有你的唯一驗證金鑰。此金鑰會與在伺服器上產生並儲存的金鑰配對，其作用類似於 SSH 金鑰。
3. 複製並在終端機中執行此指令碼，以將你的秘密驗證權杖儲存在 .gitcookies 檔案中。如果你使用的是 Windows 電腦並執行 cmd，你應遵循黃色方塊中的說明執行指令；若否則，執行一般指令碼。

第 3 步：建立 Gerrit 帳戶

Gerrit 是 Go 維護人員用於討論和檢閱程式碼提交的開源工具。

要註冊帳戶，請瀏覽 go-review.googlesource.com/login/，並使用上述相同的 Google 帳戶登入一次。

第 4 步：安裝 git-codereview 指令

必須在變更內容被接受前先檢閱 Go 的變更，不論是由誰進行變更。稱為 git-codereview 的自訂 git 指令簡化了傳送變更資料至 Gerrit 的程序。

執行以下指令安裝 git-codereview 指令，

$ go install golang.org/x/review/git-codereview@latest

確認 git-codereview 已安裝在你的殼層路徑中，以利 git 指令能找到它。檢查

$ git codereview help

是否列印說明文字而非錯誤訊息。如果它列印錯誤訊息，請確認 $GOPATH/bin 在 $PATH 中。

在 Windows 上，使用 Git-bash 時必須確認 git-codereview.exe 在你的 git 執行路徑中。執行 git --exec-path 以找出正確的位置，然後建立一個符號連結，或直接將執行檔從 $GOPATH/bin 複製到此目錄。

在提交程式碼前

本專案歡迎程式碼修補，但為了確保事情進行良好協調，你應該在任何大幅度的變更開始前，對其進行討論。建議你在問題追蹤器中透過 提出新問題 或索取 現有問題 來表達你貢獻的意願。

可貢獻的地方

Go 專案是由 go 主要儲存庫、其中包含 Go 語言的原始程式碼，以及許多 golang.org/x/... 儲存庫組成。這些儲存庫包含支援 Go 的各種工具和基礎架構。例如，golang.org/x/pkgsite 用於 pkg.go.dev，golang.org/x/playground 用於 Go playground，而 golang.org/x/tools 則包含各種 Go 工具，包括 Go 語言伺服器 gopls。你可以在 go.googlesource.com 上查看所有 golang.org/x/... 儲存庫的清單。

檢查問題追蹤器

無論你已經知道要貢獻什麼，還是正在尋找點子，問題追蹤器 永遠都是首要選擇。問題會經過分類，以分類和管理工作流程。

大多數 golang.org/x/... 儲存庫也會使用主要的 Go 問題追蹤器。但是，其中少部分儲存庫會個別管理自己的問題，因此請務必檢查你要貢獻儲存庫的正確追蹤器。

大多數的問題都將標有下列工作流程標籤之一

• 需要調查：這個問題尚未完全了解，需要分析以了解根本原因。
• 需要決策：這個問題已經了解得相當透徹，但 Go 團隊尚未決定最好的解決方式。等待決策後再撰寫程式碼會比較好。如果你有興趣處理處於這樣狀態的問題，如果一段時間後仍未做出決策，請隨時在問題的留言中「標記」維護人員。
• 需要修正：這個問題已經完全了解，而且可以撰寫程式碼來修正。

你可以使用 GitHub 的搜尋功能來尋找需要協助處理的問題。範例

• 需要調查的問題：is:issue is:open label:NeedsInvestigation
• 需要修正的問題：is:issue is:open label:NeedsFix
• 需要修正並已建議變更的問題：is:issue is:open label:NeedsFix ("golang.org/cl" OR "go.dev/cl")
• 須修正且無建議變更的問題：is:issue is:open label:NeedsFix NOT "golang.org/cl" NOT "go.dev/cl"

為任何新問題開啟一個議題

除了極微不足道的變更外，所有貢獻都應連結至現有的議題。歡迎開啟一個並討論您的計畫。這個程序讓每個人都有機會驗證設計、避免重複付出，並確保此構想符合語言和工具的目標。這也會在撰寫程式碼之前檢查設計是否健全；程式碼檢閱工具不是進行高層級討論之處。

在規劃工作時，請注意 Go 專案遵循 主要 Go 儲存庫的 6 個月開發週期。每個週期的後半段為 3 個月的功能凍結期，期間只接受錯誤修正和文件更新。新貢獻可在功能凍結期間傳送，但直到凍結期結束才執行合併。凍結適用於所有主要儲存庫以及 golang.org/x/… 儲存庫中的程式碼，這些程式碼是建置發行版所含二進位檔所需的。請參閱已販售給 標準函式庫 和 go 指令 的套件清單。

語言、函式庫或工具的重大變更（包括主要儲存庫和所有 golang.org/x 儲存庫的 API 變更，以及 go 指令的命令列變更）都必須通過 變更提案程序 才能獲得接受。

有關安全性且內容敏感的重大問題（僅限！）應回報至 security@golang.org。

透過 GitHub 傳送變更

對於已熟悉 GitHub 流程 的首次貢獻者，建議使用相同的程序進行 Go 的貢獻。即使 Go 維護人員使用 Gerrit 進行程式碼檢閱，仍已建立一個名為 Gopherbot 的機器人，可將 GitHub 提交要求同步到 Gerrit。

請照平常的方式開啟一個 GitHub 提交請求。Gopherbot 會建立一個對應的 Gerrit 變更清單（一個「CL」），並在您的 GitHub 提交請求上張貼一個連結；提交請求的更新也會反映在 Gerrit CL 中。當有人在 CL 上留言時，他們的留言也會張貼在您的提交請求中，因此您會收到通知。

應留意的是

• 若要回應審閱者（包括將 回饋意見標示為「已完成」，需要 Gerrit 帳戶，如果照建議實作。）建議熟悉 Gerrit，例如：瀏覽開放的變更清單、訂閱有興趣的變更清單的更新（透過星星圖示），或 審閱或給予其他人的變更清單一個 +1。
• 若要使用新程式碼更新拉取要求，只要將其推播至分支；可以新增更多提交，或重新定基底並強制推播（兩種樣式均可接受）。
• 如果接受請求，所有提交都將壓縮，最後的提交說明會透過串接拉取要求的標題和說明而組成。將捨棄個別提交的說明。請參閱 撰寫良好的提交訊息，了解一些建議。
• 請參閱 常見問題，以了解詳細資訊。

透過 Gerrit 傳送變更

至少在目前，無法完全同步 Gerrit 和 GitHub，因此建議學習 Gerrit。它雖然不同，但功能強大，熟悉它有助於了解流程。

概覽

以下是整體流程的概觀

• 步驟 1：從 go.googlesource.com 複製原始程式碼，並透過編譯和測試一次來確保其穩定。

  如果你正在對 主要的 Go 儲存庫 進行變更

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

  如果你正在對某個 golang.org/x/... 儲存庫（此範例中為 golang.org/x/tools）進行變更

  $ git clone https://go.googlesource.com/tools
  $ cd tools
  $ go test ./...                             # compile and test
  

• 步驟 2：從主分支建立新的分支，並在其中準備變更。若要提交變更，請使用 git codereview change；這會在分支中建立或修改單一提交。

  $ 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。

  在主要的 Go 儲存庫中

  $ ./all.bash    # recompile and test
  

  在 golang.org/x/... 儲存庫中

  $ go test ./... # recompile and test
  

• 步驟 4：使用 git codereview mail 將變更傳送給 Gerrit 審閱（雖然名稱如此，但並不會使用電子郵件）。

  $ git codereview mail     # send changes to Gerrit
  

• 步驟 5：審閱後，套用變更至同一個單一提交，並再次將其郵寄給 Gerrit

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

本節中的其餘部分將更詳細地說明這些步驟。

步驟 1：複製原始程式碼

除了最近的 Go 安裝程式，你還需要取得從正確儲存庫中簽出的來源副本。你可以將 Go 來源儲存庫簽出至本機檔案系統，只要位置在你的 GOPATH 之外即可（預設為家目錄中的 go 目錄）。請從 go.googlesource.com 複製（而非 GitHub）

Go 主儲存庫

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

golang.org/x/... 儲存庫

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

步驟 2：在新分支中準備變更

每個 Go 變更都必須在一個由主分支複製的新分支中進行。你可以使用一般的 git 指令，建立分支並將變更新增至暫存區

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

若要提交變更，請改用 git codereview change，而非 git commit。

$ git codereview change
(open $EDITOR)

你可以像平常一樣，使用你最愛的編輯器自訂提交說明。git codereview change 指令會自動在最底下新增一個獨特的 Change-Id 行。Gerrit 會使用該行，比對同一變更的連續上傳資料。請勿編輯或刪除該行。Change-Id 會類似下列範例

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

這個工具也會檢查你是否使用 go fmt 執行過來源程式碼，以及提交訊息是否符合 建議格式。

如果你需要再次編輯檔案，你可以暫存新的變更，並重新執行 git codereview change：後續的每次執行動作，都會修改現有的提交資料，同時保留 Change-ID。

請務必在每個分支中，始終只保留一個提交。如果你不小心新增更多提交，你可以使用 git rebase 將它們壓縮成 一個。

步驟 3：測試你的變更

你已 撰寫和測試你的程式碼，但在送出程式碼進行審查之前，請執行 完整目錄的所有測試，以確保變更不會損壞其他套件或程式。

在主要的 Go 儲存庫中

這可以透過執行 all.bash 來完成

$ cd go/src
$ ./all.bash

(若要在 Windows 系統下建置，請使用 all.bat)

執行一段時間並印出大量測試結果後，指令會列印以下內容，並結束

ALL TESTS PASSED

你可以使用 make.bash，而非 all.bash 來只建置編譯器和標準函式庫，而不執行測試套件。一旦完成 go 工具建置後，它會安裝在複製 Go 儲存庫的目錄下的 bin/go 中，你可以直接從該目錄中執行它。請同時參閱如何 快速測試你的變更 的說明。

在 golang.org/x/... 儲存庫中

執行整個儲存庫的測試（在本範例中為 golang.org/x/tools）

$ cd tools
$ go test ./...

如果你擔心建置狀態，你可以查看 建置儀表板。測試失敗也有可能會在程式碼審查中由 TryBot 捕捉到。

一些存放庫，例如 golang.org/x/vscode-go，將有不同的測試基礎架構，因此務必查看正在使用的存放庫文件。儲存庫根目錄的 README 檔案通常會有這些資訊。

步驟 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

如果您收到錯誤訊息，請查看 處理郵件錯誤 部分。

如果變更與公開的 GitHub 議題相關且已遵循 建議的提交訊息格式，其中一個機器人會在幾分鐘後更新議題，並在留言中將其連結到您的 Gerrit 變更。

步驟 5：在審閱後修改變更

Go 維護人員會在 Gerrit 上審閱您的程式碼，而您會透過電子郵件收到通知。您可以在 Gerrit 上看到審閱，並在上面留言。如果您偏好，也可以 使用電子郵件 回覆。

如果需要在審閱後修改變更，請在先前建立的相同分支中編輯檔案，將其加入 Git 準備區，然後使用 git codereview change 修改提交。

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

如果您不需要變更提交說明，請儲存並離開編輯器即可。請勿觸碰特殊 Change-Id 行。

再次提醒，請務必在每個分支中維持單一提交。如果您不小心新增更多提交，可以使用 git rebase 將它們 壓縮成 單一提交。

良好的提交訊息

Go 的提交訊息遵循特定慣例，我們會在本部分進行討論。

以下是良好的範例

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 工具為變更描述格式化基準資料。

參考問題

特殊的標示法「修正 #12345」會將變更與 Go 問題追蹤器 中的問題 #12345 做連結。當這個變更最終套用，問題追蹤器會自動將問題標記為已修正。

如果變更只是解決問題的部分步驟，請改寫成「更新 #12345」。這樣會在問題中留下註解，連結回 Gerrit 中的變更，但不會在變更套用後關閉問題。

如果您要對 golang.org/x/... 儲存庫傳送變更，則您必須使用 GitHub 所支援的完整語法，才能確定變更已連結至主儲存庫中的問題，而非 x/ 儲存庫。大多數的問題會追蹤在主儲存庫的問題追蹤器中。正確的格式為「修正 golang/go#159」。

審查流程

這個區段會詳細說明審查流程，以及變更郵寄後要如何開始進行審查。

初學者常犯的錯誤

當變更傳送至 Gerrit 時，通常會在幾天內進行分類。維護人員會查看並提供一些初步的審查，對於初次貢獻的貢獻者而言，通常會專注在基本的格式和常見的錯誤。這些錯誤包括

• 確認訊息未遵循 建議格式。
• 缺少連結的 GitHub 問題。絕大多數的變更都需要一個連結的問題，用以描述變更修正或實作的 bug 或功能，並且在繼續進行之前，應在追蹤器中取得共識。Gerrit 審查不會討論變更的優缺點，只會討論它的實作方式。
  只有在沒有相關問題的情況下，才會接受毫不起眼或只是格式上的變更。
• 在開發週期的凍結階段傳送變更，也就是什麼常見變更都不會接受。在這種情況下，維護人員可能會使用「R=go1.12」這類的文字來審查程式碼，表示當系統開啟新的開發視窗後，稍後會再進行審查。如果您知道這不是變更的正確時間架構，則可以自行加入註解「R=go1.XX」。

嘗試機器人

在對你的變更進行初步讀取後，維護人員會觸發嘗試機器人，一個在多個不同架構上執行完整測試套件的伺服器叢集。大多數嘗試機器人在幾分鐘內完成，屆時會在 Gerrit 中發佈一個連結讓你查看結果。

如果嘗試機器人的執行失敗，請追蹤連結並查看測試失敗的平台的完整日誌。嘗試瞭解錯誤在哪，更新你的修正程式來修正錯誤，然後重新上傳。維護人員將觸發新的嘗試機器人執行，看看問題是否已解決。

有時，這棵樹在某些平台上可能在幾個小時內中斷；如果嘗試機器人回報的失敗似乎與你的修正程式無關，請前往 建置儀表板 並查看同一平台上的其他近期提交中是否出現相同的失敗。在此情況下，請在 Gerrit 中撰寫留言，說明失敗與你的變更無關，以幫助維護人員瞭解情況。

檢閱

Go 社群非常重視徹底的檢閱。把每則檢閱留言都視為一種意見回饋：你可望對留言做出回應，方法是採取行動，例如實作建議或說服檢閱人員。

更新變更後，仔細查看檢閱留言，並確保回覆每一則留言。你可以按一下「已完成」按鈕來回覆，表示你已實作檢閱人員的建議；否則，按一下「回覆」並說明你為何未實作，或你採取了什麼其他措施。

變更經過幾輪檢閱是很正常的，其中一位或多位檢閱人員每次提出新的留言，然後等到更新的變更後才再次檢閱。即使是有經驗的貢獻者也會經歷這個週期，所以不要因此而氣餒。

投票慣例

在做出決定時，檢閱人員會對你的變更套用程式碼審查「投票」。有兩種可能的投票

• +2 變更已核准進行合併。只有 Go 維護人員（也稱為「核准人」）才能投下 +2 票。
• +1 變更看起來不錯，但檢閱人員要求在核准它之前進行一些小變更，或者他們不是維護人員，無法核准它，但希望鼓勵核准。

要提交變更，必須獲得維護人員的程式碼審查 +2。

維護人員也可以對變更套用擱置 +1 票，以標記不應立即提交的變更（例如，因為變更中新 API 的 提案審查 尚未完成）。

要提交變更，必須沒有維護人員給予擱置 +1 票。

最後，要提交變更，變更必須有兩位 Google 員工參與，其中一位作為變更的上傳者或至少投票程式碼審查 +1 的檢閱人員。此要求是出於合規性和供應鏈安全考量。

提交核准的變更

當變更準備好時，維護人員將會提交變更，並將其新增為 Gerrit 儲存庫中的提交。

這兩個步驟（核准和提交）是分開的，因為在某些情況下，維護人員可能想要核准變更，但不會立刻提交變更（例如：樹狀結構可能暫時凍結）。

提交變更會將變更簽入儲存庫。變更說明中會包含程式碼檢閱的連結，該連結會更新為儲存庫中變更的連結。由於用於整合變更的方法是 Git 的「挑選」，因此提交操作會變更儲存庫中的提交雜湊。

倘若您的變更已核准幾天但尚未提交，請隨時在 Gerrit 中撰寫意見，要求提交。

更多資訊

除了此處的資訊外，Go 社群還維護一個 CodeReview wiki 頁面。當您更深入瞭解檢閱流程時，歡迎對此頁面進行投稿。

其他主題

本節收集了其他一些意見，這些意見不屬於問題/編輯/程式碼檢閱/提交流程本身。

Gopls

在處理主 Go 儲存庫並與您的編輯器一起使用 gopls 時，gopls 呼叫的 go 命令必須與您正在處理的原始程式碼版本相符。go 命令可以使用 make.bash 建立，而且 bin 目錄應該要新增到您的 PATH 中。請參閱 Gopls：進階主題 以取得其他詳細資料。

著作權標頭

為了避免混亂，也避免必須持續更新清單，因此 Go 儲存庫中的檔案不會列出作者姓名。您的姓名將會顯示在 變更記錄 中。

您貢獻的新檔案應該使用標準著作權標頭

// Copyright 2024 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.

儲存庫中的檔案會在新增的年份受著作權保護。請勿更新您變更的檔案中的著作權年份。

電子郵件錯誤的疑難排解

最常見的 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

然後使用此命令，使用此備用電子郵件地址變更提交

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

然後執行來重試

$ git codereview mail

快速測試變更

針對程式碼樹中的每一處變更執行 all.bash 都很費時。即使強烈建議在送出變更前執行，在正常的開發週期中，您可能只想要編譯和測試您正在開發的套件。

• 一般來說，您可以執行 make.bash 取代 all.bash，僅重新建置 Go 工具鏈而不用執行整個測試套件。或者，您可以執行 run.bash，僅執行整個測試套件而不用重新建置工具鏈。您可以將 all.bash 視為 make.bash 接著 run.bash。
• 在此部分中，我們會將您複製 Go 儲存庫的目錄稱為 $GOROOT。由 $GOROOT/src/make.bash 建置的 go 工具將會安裝在 $GOROOT/bin/go中，而且您可以呼叫它來測試您的程式碼。舉例來說，如果您修改了編譯器，而且希望測試它如何影響您自己專案的測試套件，只要使用它執行 go test 即可

  $ cd <MYPROJECTDIR>
  $ $GOROOT/bin/go test
  

• 如果您正在變更標準函式庫，您可能不需要重新建置編譯器：您可以只執行您已變更套件的測試。您可以使用您通常使用的 Go 版本來執行，或者使用從您的複製建置的 Go 編譯器（有時需要這樣做，因為您正在修改的標準函式庫程式碼可能需要比您已安裝的穩定版更新的版本）。

  $ cd $GOROOT/src/crypto/sha1
  $ [make changes...]
  $ $GOROOT/bin/go test .
  

• 如果您正在修改編譯器本身，您可以僅重新編譯 compile 工具（此為 go build 在編譯每一個套件時呼叫的內部二進位檔案）。在那之後，您會想要透過編譯或執行某些內容來測試它。

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

  對於 Go 工具鏈的其他內部工具，例如 asm、cover、link 等等，也是一樣的步驟。只要重新編譯並使用 go install cmd/<TOOL> 安裝工具，然後使用建置的 Go 二進位檔案來測試它即可。
• 除了每個套件的標準測試之外，在 $GOROOT/test 中還有一個頂層測試套件，它包含了幾個黑盒和回歸測試。測試套件會由 all.bash 執行，但您也可以手動執行

  $ $GOROOT/bin/go test cmd/internal/testdir
  

指定校閱者/副本收件者

除非另有明確說明，例如準備送出變更之前的討論，最好不要指定校閱者。所有變更都會自動副本收件給 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 工作流程中，這就如同其他人在 Pull Request 附件中附加提交）。Gerrit 提供可協助您匯入其他開發者提供的建議變更的指令存取權，以便您在本地進行檢閱/測試。請從 CL 的 Gerrit 頁面中開啟「⋮」功能表，然後按一下「下載修正程式」連結以匯入您想要匯入的變更。依照您偏好的 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 組態檔案中（通常為您首頁目錄中的 .gitconfig）：

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

發送多筆相關變更

進階使用者可能想要堆疊單一分支中的相關提交。Gerrit 容許變更相互依賴，形成此類的依賴關係鏈。每項變更都需要分別獲得核准和提交，但檢閱者可以看見依賴關係。

若要傳送一組相關變更，請在同一個分支下將每一項變更設為不同的提交，然後執行

$ git codereview mail HEAD

請務必明確定義 HEAD，因為在傳送單一變更時通常不需要。您可以在 git-codereview 文件 中找到更詳盡的資料。