【译】Go 语言项目源码贡献官方指导文档

之前给 Go 语言项目源码提交过一些 commits，期间阅读他们的官方指导文档的时候以为这篇指导文档能够做为绝佳的关于大型软件项目的规范管理的参考，由于最近又提交了几个 commits，就又把这篇文档再看了一遍，有感于 Go 团队在项目管理和工程实践上的一些宝贵经验，就把文档翻译成了中文；一来为了更加深刻地理解 Go 语言团队的项目工程最佳实践，二来则是为了给其余有意给 Go 语言源码提交贡献的开发者提供一点参考。

导言

Go 语言项目欢迎全部的代码贡献者。

这是一份指导你完成向 Go 语言项目贡献代码整个流程的文档，会略微跟其余开源项目所使用的指导文档有所不一样。咱们假设阅读者已经对 Git 和 Go 有基本的理解以及具有相关的基础知识。

除了这里所介绍的信息，Go 语言社区也维护了一份关于代码评审的 wiki 页面。在你学习评审流程期间，欢迎随时给这份 wiki 贡献、补充新内容。

请注意， gccgo 前端的文档在另外一处；看这里：Contributing to gccgo。

成为一个代码贡献者

概述

第一步须要注册成为一个 Go contributor 以及配置你的环境。这里有一份包含了所需步骤的清单：

• 步骤 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 工具。

若是你图省事的话，能够直接用自动化工具帮你完成上面的所有步骤，只需运行：

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

这个章节的后面部分将会更加详尽地阐述上面的每个步骤。若是你已经完成上面的全部步骤（无论是手动仍是经过自动化工具），能够直接跳到贡献代码以前部分。

步骤 0: 选择一个 Google 帐号

每个提交到 Go 语言的代码贡献都是经过一个绑定了特定邮箱地址的 Google 帐号来完成的。请确保你在整个流程中自始至终使用的都是同一个帐号，固然，后续你提交的全部代码贡献也是如此。你可能须要想好使用哪种邮箱，我的的仍是企业的。邮箱类型的选择将决定谁拥有你编写和提交的代码的版权。在决定使用哪一个帐户以前，你大概要和你的雇主商议一下。

Google 帐号能够是 Gmail 邮箱帐号、G Suite 组织帐号，或者是那些绑定了外部邮箱的帐号。例如，若是你想要使用一个已存在且并不属于 G Suite 的企业邮箱，你能够建立一个绑定了外部邮箱的 Google 帐号。

你还须要确保你的 Git 工具已经正确配置好你以前选定的邮箱地址，用来提交代码。你能够经过 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 语言项目(进行评审)以前，你必须先签署下面两种证书协议的其中之一。最后的代码版权归属于谁，将决定你应该签署哪种协议。

• 若是你我的是版权持有方，你就须要赞成 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 来访问它。按照如下的步骤进行：

1. 访问 go.googlesource.com 而后点击页面右上角菜单条上的 "Generate Password" 按钮。接着你会被重定向到 accounts.google.com 去登录。
2. 登录以后，你会被引导到一个标题为 "Configure Git" 的网页。这个网页包含了一段个性化的脚本代码，运行这个脚本以后会自动生成身份认证的密钥并配置到 Git 里面去。这个密钥是和另外一个在远端 Server 生成并存储的密钥成对的，相似于 SSH 密钥对的工做原理。
3. 复制这段脚本并在你的我的电脑上的终端运行一下，你的密钥认证 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 写个评论要求合入。

更多信息

除了这里的信息，Go 语言社区还维护了一个代码评审的 wiki 页面。随时欢迎你在学习相关的评审流程之时为这个页面贡献、补充新内容。

其余主题

这个章节收集了一些除了 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

发送多个依赖的变动

老司机用户可能会想要把相关的 commits 叠加到一个单独的分支上。Gerrit 容许多个代码变动之间相互依赖，造成这样的依赖链。每个变动须要被单独地核准和提交，可是依赖对于评审人来讲是可见的。

要发送一组依赖的代码更改，请将每一个变动做为不一样的 commit 保存在同一分支下，而后运行：

$ git codereview mail HEAD

要确保显示地指定 HEAD ，不过这在单个变动的场景里一般是不须要指定的。

英文原文地址

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