Contribution Guide

Go项目欢迎所有贡献者.

本文档是帮助您完成Go项目贡献过程的指南,该过程与其他开放源代码项目所使用的过程略有不同. 我们假设您对Git and Go有基本的了解.

除了此处的信息外,Go社区还维护一个CodeReview Wiki页面. 在学习审核过程时,随时为Wiki做出贡献.

请注意, gccgo前端位于其他位置. 请参阅为gccgo贡献内容 .

Becoming a contributor

Overview

第一步是注册为Go贡献者并配置您的环境. 以下是需要执行的步骤的清单:

如果您愿意,可以通过自动化工具完成这些步骤. 赶紧跑:

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

本章的其余部分将详细说明这些说明. 如果您已完成上述步骤(手动或通过工具),请跳至" 贡献代码之前" .

Step 0: Select a Google Account

通过具有特定电子邮件地址的Google帐户为Go做出了贡献. 确保在整个过程中以及以后的所有捐款中使用相同的帐户. 您可能需要决定使用个人地址还是公司地址. 选择将取决于谁将拥有您将要编写和提交的代码的版权. 在决定使用哪个帐户之前,您可能需要与雇主讨论此主题.

Google帐户可以是Gmail电子邮件帐户,G Suite组织帐户或与外部电子邮件地址关联的帐户. 例如,如果您需要使用未通过G Suite管理的现有公司电子邮件,则可以创建一个与现有电子邮件地址关联的帐户.

您还需要确保将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

Step 1: Contributor License Agreement

在将您的第一个更改发送到Go项目之前,您必须完成以下两个CLA中的一个. 您应该签署哪个CLA取决于谁拥有您作品的版权.

您可以在Google Developers Contributor许可协议网站上查看当前已签署的协议,也可以签署新的协议 . 如果您的贡献的版权所有者已经完成了与另一个Google开放源项目有关的协议,则无需再次完成该协议.

如果您要提交的代码的版权所有者有所更改(例如,如果您代表新公司开始提供代码),请发送邮件到golang-dev邮件列表 . 这将使我们知道情况,因此我们可以确保完成适当的协议并更新AUTHORS文件.

Step 2: Configure git authentication

Go的主要存储库位于go.googlesource.com (由Google托管的Git服务器). 通过您的Google帐户对网络服务器进行身份验证,但是您还需要在计算机上配置git才能访问它. 请按照以下步骤操作:

  1. 访问go.googlesource.com ,然后单击页面右上方菜单栏中的"生成密码". 您将被重定向到account.google.com进行登录.
  2. 登录后,您将进入标题为" Configure Git"的页面. 该页面包含个性化脚本,在本地运行时,该脚本将配置Git使其持有唯一的身份验证密钥. 该密钥与生成并存储在服务器上的密钥配对,类似于SSH密钥的工作方式.
  3. 在您的终端本地复制并运行此脚本,以将您的秘密身份验证令牌存储在.gitcookies文件中. 如果您使用的是Windows计算机并运行cmd ,则应按照黄色框中的说明运行命令;否则,请执行以下操作: 否则运行常规脚本.

Step 3: Create a Gerrit account

Gerrit是Go维护人员用来讨论和审查代码提交的开源工具.

要注册您的帐户,请访问go-review.googlesource.com/login/并使用您在上面使用的同一Google帐户登录一次.

Step 4: Install the git-codereview command

无论是谁进行更改,都必须先对Go所做的更改进行审查,然后再接受更改. 一个自定义的git命令git-codereview简化了将更改发送到Gerrit的过程.

通过运行安装git-codereview命令,

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

确保在您的shell路径中安装了git-codereview ,以便git命令可以找到它. 检查一下

$ git codereview help

打印帮助文本,而不是错误. 如果显示错误,请确保$GOPATH/bin$PATH .

在Windows上,使用Git的bash时,必须确保git-codereview.exe在你git的exec路径. 运行git --exec-path来找到正确的位置,然后创建一个符号链接,或者只是将可执行文件从$GOPATH/bin复制到此目录.

Before contributing code

该项目欢迎代码补丁,但是为了确保所有内容都协调良好,您应该在开始工作之前讨论任何重大更改. 建议您通过提交新问题或声明现有问题来表明您打算在问题跟踪程序中做出贡献.

Check the issue tracker

无论您已经知道要做出什么贡献,还是正在寻找一个想法, 问题跟踪器始终是您的第一要务. 对问题进行分类以对其进行分类并管理工作流程.

大多数问题将使用以下工作流程标签之一进行标记:

您可以使用GitHub的搜索功能查找需要帮助的问题. 例子:

Open an issue for any new problem

Excluding very trivial changes, all contributions should be connected to an existing issue. Feel free to open one and discuss your plans. This process gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits inside the goals for the language and tools. It also checks that the design is sound before code is written; the code review tool is not the place for high-level discussions.

在计划工作时,请注意Go项目遵循六个月的开发周期 . 每个周期的后半部分是三个月的功能冻结,在此期间仅接受错误修复和文档更新. 可以在功能冻结期间发送新的文稿,但是在冻结结束之前它们不会合并.

语言,库或工具的重大更改必须经过更改建议流程才能被接受.

Sensitive security-related issues (only!) should be reported to security@golang.org.

Sending a change via GitHub

鼓励已经熟悉GitHub流程的初次贡献者对Go贡献使用相同的过程. 即使Go维护人员使用Gerrit进行代码审查,也已经创建了一个名为Gopherbot的机器人来将GitHub拉取请求同步到Gerrit.

像往常一样打开拉取请求. Gopherbot将创建相应的Gerrit更改,并将其链接发布到您的GitHub pull请求中; 拉取请求的更新也将反映在Gerrit更改中. 当有人对更改发表评论时,他们的评论也将发布在您的请求中,因此您将收到通知.

注意事项:

Sending a change via Gerrit

至少目前无法完全同步Gerrit和GitHub,因此我们建议学习Gerrit. 它与众不同,但功能强大且熟悉它会帮助您理解流程.

Overview

这是整个过程的概述:

本节的其余部分将更详细地描述这些步骤.

Step 1: Clone the Go source code

除了最近的Go安装之外,您还需要从正确的存储库中签出源的本地副本. 您可以将Go源存储库检出到本地文件系统中的任何位置,只要它在GOPATH之外GOPATH . 从go.googlesource.com (不是GitHub)克隆:

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

Step 2: Prepare changes in a new branch

每个Go更改都必须在从master分支创建的单独分支中进行. 您可以使用普通的git命令创建分支并将更改添加到登台区域:

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

要提交更改,而不是git commit ,请使用git codereview change .

$ git codereview change
(open $EDITOR)

您可以照常在自己喜欢的编辑器中编辑提交描述. git codereview change命令将在底部附近自动添加唯一的Change-Id行. Gerrit使用该行来匹配同一更改的连续上载. 不要编辑或删除它. 更改ID如下所示:

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

该工具还会检查您是否在源代码上运行了go fmt ,并且提交消息是否遵循建议的format .

如果您需要再次编辑文件,则可以进行新更改并重新运行git codereview change :每次后续运行都将在保留Change-Id的同时修改现有提交.

确保在每个分支中始终保留一个提交. 如果您错误地添加了更多提交,则可以使用git rebase它们 rebase 在一起 .

Step 3: Test your changes

您已经编写并测试了代码 ,但是在将代码发送出去进行检查之前进行以确保所做的更改不会破坏其他程序包或程序:

$ cd go/src
$ ./all.bash

(要在Windows下使用all.bat构建,这还需要将环境变量GOROOT_BOOTSTRAP设置为用于引导编译器的Go树GOROOT_BOOTSTRAP的目录.)

运行一段时间并打印大量测试输出后,该命令应通过打印完成,

ALL TESTS PASSED

您可以使用make.bash而不是all.bash来构建编译器和标准库,而无需运行测试套件. 构建go工具后,它将以bin/go形式安装在您克隆Go存储库的目录下,您可以从那里直接运行它. 另请参见有关如何快速测试更改的部分.

Step 4: Send changes for review

更改准备就绪并在整个树上进行测试后,将其发送以供审核. 这是通过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更改链接到注释中.

Step 5: Revise changes after a review

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它们 git rebase 在一起 .

Good commit messages

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

First line

变更说明的第一行通常是变更的简短单行摘要,以主要受影响的软件包为前缀.

一条经验法则是,应该这样写才能完成句子"此更改修改了_____". 这意味着它不是以大写字母开头,不是完整的句子,而是实际上总结了更改的结果.

第一行后跟空白行.

Main content

本说明的其余部分将详细阐述,并应提供有关更改的上下文并解释更改的作用. 就像用Go中的注释一样,用正确的标点词完整地写句子. 不要使用HTML,Markdown或任何其他标记语言.

如果更改影响性能,请添加任何相关信息,例如基准数据. 通常,使用Benchstat工具来格式化基准数据以进行更改描述.

Referencing issues

特殊记号"修复#12345"在Go问题跟踪器中将更改与问题12345相关联. 最终应用此更改后,问题跟踪器将自动将问题标记为已修复.

如果更改只是解决问题的一部分,请使用符号"更新#12345". 这将在问题中留下评论,并链接回Gerrit的更改,但在应用更改时不会解决问题.

如果要发送对子存储库的更改,则必须使用GitHub支持的标准语法,以确保将更改链接到主存储库而不是子存储库中的问题. 在主存储库的问题跟踪器中跟踪所有问题. 正确的格式是"修复golang / go#159".

The review process

本节详细说明了审阅过程,以及在邮寄更改后如何进行审阅.

Common beginner mistakes

当将更改发送给Gerrit时,通常会在几天之内对其进行分类. 维护人员将进行查看并提供一些初步的评论,初学者通常会着重于基本的化妆品和常见错误. 这些包括:

Trybots

在初步了解您的更改之后,维护人员将触发trybots,这是一台服务器集群,将在几种不同的体系结构上运行完整的测试套件. 大多数的自动程序会在几分钟内完成,这时将在Gerrit中发布一个链接,您可以在其中查看结果.

如果trybot运行失败,请单击链接并检查测试失败的平台的完整日志. 尝试了解造成问题的原因,更新补丁程序以对其进行修复,然后再次上传. 维护人员将触发新的trybot运行,以查看问题是否已解决.

有时,树可以在某些平台上折断几个小时. 如果trybot报告的故障似乎与您的补丁程序无关,请转到Build Dashboard并检查是否在同一平台上的其他最近提交中出现了相同的故障. 在这种情况下,请随时在Gerrit中写评论以提及失败与您的更改无关,以帮助维护人员了解情况.

Reviews

Go社区非常重视全面的审查. 可以将每条评论评论视为一张票:希望您通过执行建议以某种方式"关闭"该评论,或者通过实施建议或说服评论者.

更新更改后,请查看审阅注释,并确保对每个答复进行答复. 您可以点击"完成"按钮来回复,表明您已实施审阅者的建议; 否则,请单击"答复"并说明为什么还没有做,或者您做了什么.

进行几轮审阅是非常正常的,每次都会有一个或多个审阅者发表新评论,然后等待更新后再进行审阅. 即使是经验丰富的贡献者,也会发生此周期,因此不要气cycle.

Voting conventions

当他们做出决定时,审阅者将对您的更改进行"投票". Gerrit投票系统涉及一个介于-2到+2之间的整数:

Submitting an approved change

After the code has been +2'ed, an approver will apply it to the master branch using the Gerrit user interface. This is called "submitting the change".

这两个步骤(批准和提交)是分开的,因为在某些情况下,维护人员可能希望批准它,而不是立即提交(例如,树可能被暂时冻结).

提交更改会将其检入存储库. 变更描述将包含指向代码审阅的链接,该链接将通过指向存储库中变更的链接进行更新. 由于用于集成更改的方法是Git的" Cherry Pick",因此提交操作将更改存储库中的提交哈希.

如果您的更改已被批准了几天而没有提交,请随时在Gerrit中写评论以请求提交.

More information

除了此处的信息外,Go社区还维护一个CodeReview Wiki页面. 当您了解有关审核过程的更多信息时,请随时为该页面做出贡献.

Miscellaneous topics

本节收集了一些其他问题,这些问题不在问题/编辑/代码审查/提交过程本身之外.

Go储存库中的文件不会列出作者姓名,这既可以避免混乱,又可以避免使列表保持最新状态. 取而代之的是,您的姓名将出现在更改日志中,并出现在CONTRIBUTORS文件中,甚至在AUTHORS文件中. 这些文件会定期从提交日志中自动生成. AUTHORS文件定义了谁是" The Go Authors"(版权所有者).

您贡献的新文件应使用标准的版权标题:

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

(如果要在2020年或以后阅读,请使用当年.)存储库中的文件在添加年份即受版权保护. 不要在更改的文件上更新版权年份.

Troubleshooting mail errors

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

Quickly testing your changes

对代码树的每次更改运行all.bash都很麻烦. 即使强烈建议在发送更改之前运行它,但在正常开发周期中,您可能只希望编译和测试正在开发的程序包.

Contributing to subrepositories (golang.org/x/...)

如果您要对子存储库进行更改,请使用go get获得Go软件包. 例如,要贡献给golang.org/x/oauth2 ,请通过运行以下代码来检查代码:

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

然后,将目录更改为包的源目录( $GOPATH/src/golang.org/x/oauth2 ),并遵循常规的贡献流程.

Specifying a reviewer / CCing others

除非另有明确说明,例如在导致发送更改的讨论中,否则最好不要指定审阅者. 所有更改都会自动抄送至golang-codereviews@googlegroups.com邮件列表. 如果这是您的第一次更改,为防止垃圾邮件,在邮件列表上显示之前可能要进行审核.

您可以使用-r-cc选项指定审阅者或CC感兴趣的-cc . 两者都接受以逗号分隔的电子邮件地址列表:

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

Synchronize your client

在工作时,其他人可能已将更改提交到存储库. 要更新您的本地分支,请运行

$ git codereview sync

(在幕后运行git pull -r .)

Reviewing code by others

作为审阅过程的一部分,审阅者可以直接提出更改建议(在GitHub工作流中,这是将提交附加到拉取请求的其他人). 您可以将其他人提出的这些更改导入到本地Git存储库中. 在Gerrit审查页面上,单击右上角的"下载▼"链接,复制" Checkout"命令,然后从本地Git存储库中运行它. 它看起来像这样:

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

要还原,请切换回您所在的分支.

Set up git aliases

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

Sending multiple dependent changes

Advanced users may want to stack up related commits in a single branch. Gerrit allows for changes to be dependent on each other, forming such a dependency chain. Each change will need to be approved and submitted separately but the dependency will be visible to reviewers.

要发出一组相关的更改,请将每个更改作为不同的提交保留在同一分支下,然后运行:

$ git codereview mail HEAD

确保明确指定HEAD ,发送单个更改时通常不需要.

by  ICOPY.SITE