Go 项目贡献讲习班

Go Blog 中文翻译 /

本文为官方 Go Blog 的中文翻译，详见翻译说明

Steve Francia, Cassandra Salisbury, Matt Broberg, Dmitri Shuralyov
2017年8月9日

活动概述

在GopherCon的社区日期间，Go团队举行了两个研讨会，我们与人们一起工作，以帮助他们为Go项目做出第一笔贡献。这是Go项目第一次尝试这样的事情。我们有约140名参与者和约35人自愿作为导师。 Mentors不仅因帮助他人而产生模糊的温暖感觉，而且还非常时尚的Go Mentor卡车司机帽子。我们有来自北美和南美，非洲，欧洲，亚洲和澳大利亚的不同年龄和经验水平的贡献者。这确实是Gophers在GopherCon上的一次全球合作。

我们举办研讨会的原因之一是它充当强制功能，使我们能够改善贡献者的体验。在准备研讨会时，我们重新编写了贡献者指南，包括添加了“疑难解答”部分并构建了一个工具go-contrib-init，该工具可以自动设置开发环境以做出贡献去。

对于讲习班本身，我们开发了演示文稿“为Go贡献''，并在活动期间演示了仪表板/计分板。计分板旨在鼓励我们大家共同努力，实现共同的目标，即提高我们的集体得分。参与者执行诸如注册帐户，创建更改列表(也称为CL，类似于拉取请求)，修改CL或提交CL之类的操作时，他们将总得分提高了1、2或3分。

布拉德·菲茨帕特里克(Brad Fitzpatrick)今年待在GopherCon的家里，已经准备就绪，正在等待审查所有提交的CL。他的评论速度如此之快，以至于许多人认为他是一个自动机器人。在内部，我们的团队现在将他称为“ BradBot”，主要是因为我们敬畏并且有点嫉妒。

影响

参加研讨会的人员(在研讨会的一周内)总共提交了65个CL。其中有44个来自以前从未在Go项目中为任何回购交易做过贡献的贡献者。这些捐款中有一半(22)已被合并。我们即将冻结即将发布的1.9版本时，许多其他代码都在等待代码库解冻。除了CL之外，许多还以bug报告，园艺任务和其他类型的贡献的形式为项目做出了贡献。

最常见的贡献类型是在文档中使用的示例函数。 Go用户调查确定我们的文档明显缺少示例。在演示中，我们要求用户找到他们喜欢的软件包并添加示例。在Go项目中，示例在Go文件中以代码形式编写(具有特定的命名)，并且go doc工具将其与文档一起显示。这是一个完美的第一个贡献，因为它可以在冻结过程中进行合并，这对我们的用户至关重要，而且它的范围相对较窄。

添加的示例之一是创建Stringer，这是Go中使用更广泛的接口之一。 CL 49270

除示例外，许多人还提供了重要的错误修复程序，包括：

-CL 48988修复issue#21029
-CL 49050修复issue#20054
-CL 49031修复issue#20166
-CL 49170修复issue#20877

有些人甚至想到了要修复的错误，这使我们感到惊讶。 Nikhita到达准备处理issue#20786的时候，她确实提交了CL 48871，此后她发了推文：

不仅取得了很大的进步，而且最重要的是，我们缩小了Go核心团队与广大社区成员之间的差距。 Go团队中的许多人指出，社区成员正在向他们传授有关Go项目的知识。社区中的人们(亲自或在Twitter上)表示欢迎参加该项目。

未来

这次活动取得了成功，远远超出了我们的预期。 Go团队经理Sameer Ajmani说：“对于Go团队来说，贡献者研讨会非常有趣且富有教育意义。当用户触碰到流程中的粗糙边缘时，我们感到非常高兴，并为他们在仪表板上站起来而庆祝。得分达到1000太棒了。”

我们正在研究使此研讨会更易于举办的未来活动(如聚会和会议)的方法。我们最大的挑战是提供足够的指导，以便用户获得支持。如果您有任何想法或想在此过程中提供帮助，请让我知道。

我已邀请活动的一些参与者在下面分享他们的经验：

我的贡献经验

by Cassandra

当我听说参加go-contrib研讨会时，我感到非常兴奋，然后我被吓到了。我受到围棋团队成员的鼓励，所以我想了什么。

当我走进房间时(实话实说，我因为迟到而跑进了房间)，我很高兴看到房间挤满了人。我到处寻找戴着地鼠帽的人，这是他们是老师的主要标志。我坐在有两个帽子和三个非帽子的16个圆桌之一中。调出我的屏幕并准备好滚动…

杰西·弗雷泽(Jess Frazelle)站起来开始演讲，并为小组提供了链接以便于跟踪。

杂音从一股深沉的暗流变成一阵响亮的声音，人们使用Go设置计算机，他们跳过以确保设置了GOPATH，然后……等待着Gerrit吗？

我们大多数人都必须对Gerrit有所介绍。我不知道那是什么，但是幸运的是有一个方便的幻灯片。 Jess解释说，它是GitHub的替代产品，具有稍微更高级的代码审查工具。然后，我们经历了GitHub vs Geritt术语，因此我们对过程有了更好的了解。

好的，现在是时候成为一个非常的 Go 贡献者了。

为了使这种情况比以前更加令人兴奋，Go团队建立了一个游戏，在该游戏中，我们可以根据Gerrit得分系统，以小组的形式跟踪获得多少积分。

看到您的名字出现在黑板上，倾听每个人的兴奋，令人陶醉。它还激发了团队合作感，从而产生了包容感，让您感觉自己确实是Go社区的一部分。

通过6个步骤，一个大约80人的房间能够学习如何在一个小时内做出贡献。那是壮举！

这几乎不像我预期的那样困难，而且对于一个新手来说也不超出范围。它以积极，切实的方式培养了社区意识，并在围棋贡献的杰出过程中树立了包容感。

我个人要感谢Go团队，戴着帽子的Gopher导师以及我的参与者，使这成为我GopherCon上最难忘的时刻之一。

我的贡献经验

作者 Matt

我一直觉得编程语言很吓人。它是使世界能够编写代码的代码。考虑到影响，肯定比我聪明的人应该在做这件事.但这种恐惧是需要克服的。因此，当有机会参加一个研讨会，为我喜欢的新编程语言做出贡献时，我很兴奋地看到我可以如何以及我如何能提供帮助。一个月后，我现在确信任何人和每个人都可以(也应该)为Go做出贡献。

下面是我从0到2贡献的非常详细的步骤：

设置

鉴于Go使用了Gerrit，我开始为它设置我的环境。 Jess Frazzelle的指南是一个不容错过的好地方。

当您克隆 Go 存储库时，真正的乐趣就开始了。具有讽刺意味的是你无法在 $GOPATH中编写 Go 源码，因此我将其放在其他工作区( ~/Develop).

cd $DEV # That's my source code folder outside of $GOPATH
git clone --depth 1 https://go.googlesource.com/go

然后安装便捷的工具 go-contrib-init:

go get -u golang.org/x/tools/cmd/go-contrib-init

现在您可以从上面克隆的项目 go-contrib-init 的 go/ 目录下运行 go-contrib-init。

接下来，安装 codereview：

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

该软件包包括 git change 和 git mail 它们将分别替换 git commit 和 git push。

好的，安装不碍事。现在在这里设置您的 Gerrit 帐户, 然后签署 CLA。您可以在 cla.developers.google.com/clas 查看历史。

准备就绪，接下来如何贡献？

开始贡献

在研讨会中，他们将我们发送到 scratch 存储库中，该存储库是一个可以四处浏览以掌握工作流程的安全地方：

cd $(go env GOPATH)/src/golang.org/x
git clone --depth 1 [[https://go.googlesource.com/scratch][go.googlesource.com/scratch]]

第一站是进入cd 并运行 go-contrib-init 以确保您已准备好进行贡献：

go-contrib-init
All good. Happy hacking!

从那里，我创建了一个以GitHub帐户命名的文件夹，进行了 git add -u。 git change 它有一个哈希跟踪您的工作，就像 git commit 一样。接下来设置 package: description，我使用 git mail 来提交代码到 Gerrit 上。

需要注意两个地方：git change 与 git commit --amend 类似，因此如果你想修改你的补丁，可以使用 add 然后 change。其次，你可以在个人 Gerrit 页面了查看你所提交的补丁。

几次回来之后，我正式有了一个贡献！如果 Jaana 是对的，它可能是第一个使用表情符号的✌️。

开始正式提交

初始仓库很有趣，但是有很多方法可以深入 Go 的程序包并收回。在这一点上，我浏览了许多可用的软件包，以查看对我有用的和有趣的东西。我会找到一个软件包列表，然后转到源代码以查看 go/src/ 文件夹下的内容：

我决定看看我能在 regexp 包中做些什么，也许是出于对正则表达式的热爱和恐惧。在这里，我切换到软件包的网站视图 (每个标准软件包都可以在 godoc.org/$PACKAGENAME 上找到)。在这里，我注意到 QuoteMeta 缺少了其他功能具有的相同级别的详细示例(我可以使用 Gerrit 进行练习)。

我开始查看 go/src/regexp试图找到在哪里添加示例，但很快就迷路了。幸运的是， Francesc 他向我介绍了所有示例实际上如何在 example_test.go 文件中进行在线测试。他们遵循测试用例的格式，然后注释掉“输出”，然后给出测试答案。例如：

func ExampleRegexp_FindString() {
    re := regexp.MustCompile("fo.?")
    fmt.Printf("%q.", re.FindString("seafood"))
    fmt.Printf("%q.", re.FindString("meat"))
    // Output:
    // "foo"
    // ""
}

有点酷吧？我跟随 Francesc 的领导，并添加了一个函数ExampleQuoteMeta，并添加了一些我认为会有所帮助的函数。
然后是 git change 和 git mail 更新到 Gerrit!

我不得不说，史蒂夫·弗朗西亚(Steve Francia) 挑战我去『发现并解决未解决的问题』，因此我在补丁中包括了 QuoteMeta 的一些文档更改。考虑到额外的范围，它将耗费更长的时间，但是我认为在这方面值得。

我已经可以听到您的问题：我是如何验证它的工作的？说实话并不容易。运行无法工作 go test example_test.go -run QuoteMeta -v，因为我们在 $GOPATH 外面。我一直在努力弄明白这一点，直到看了 Kale Blakenship 的这篇文章，赶快收藏下。

现在你可以在这里看到我的贡献。我也希望你看到的是，进入贡献的流程是多么简单。如果您像我一样，那么您将擅长在文档中找到一个小的打字错误或缺少的示例，以便开始习惯 git codereview 的工作流程。在那以后可以寻找开放的问题，理想情况下是一个标记为即将发布的版本，并尝试一下。无论你选择做什么，一定要去做。Go 团队向我证明了他们是多么在乎帮助我们所有人做出贡献。我都等不及下一份 git mail了。

我的导师经验

作者 Dmitri

我期待作为导师参加贡献研讨会活动。我对活动有很高的期望，并且在活动开始之前就认为这是一个很好的想法。

在 2014 年 5 月 10 日做出了我的第一个贡献。我记得从我想要贡献的那一刻起大约是四个月，直到那天，我实际上发送了我的第一个 CL。花了那么长时间才鼓起勇气，完全致力于弄清楚这个过程。当时我是一名经验丰富的软件工程师。尽管如此，Go 的贡献过程感觉很陌生-与我已经熟悉的所有其他过程不同-因此看起来很吓人。虽然它有很好的文档，但是我一直没有时间且对未知的事物敬而远之。

过了几个月后，我决定在即将到来的周末花一整天的时间来弄清楚这个过程。我留出了整个星期六做一件事：发送我的第一个 CL 去。我打开贡献指南，从最上面开始执行所有步骤。不到一个小时，我就做完了。我已经发送了我的第一个 CL。我既敬畏又震惊。在敬畏中，因为我终于送了一份稿子去了，它被接受了！震惊，因为，为什么我等了这么久才最终做到这一点？按照贡献指南中的步骤进行非常容易，整个过程进行得非常顺利。如果有人告诉我，我会在一小时内完成，而且不会出错，我会更快地完成它！

这将我带到了这个活动，也是为什么我认为这是一个好主意。对于那些曾经想要贡献自己的人，但是对这个陌生和似乎漫长的过程感到畏惧的人(就像我在那四个月中一样)，这是他们的机会！不仅可以很容易地通过参加活动来解决问题，而且 Go 团队和有帮助的志愿者导师也会在一路上帮助您。

尽管我对活动的期望值已经很高，但还是超出了我的期望值。首先，Go 团队已经做好了充分的准备，并投入了大量资金，使这一活动更加令每个人都感到愉快。有一个非常有趣的演示，快速回顾了所有的贡献步骤。有一个为活动制作的仪表板，每个人成功完成的步骤都会得到全球分数的奖励。这使得它成为一个非常适合学习和社交的活动！最后，也是最重要的，他们是像Brad Fitzpatrick 这样的 Go 团队成员，在幕后帮助快速审核 CLs！这意味着提交的 CLs 很快就收到了评论，并提供了可操作的后续步骤，这样每个人都可以继续前进并了解更多信息。

我最初预计事件会有些枯燥，因为贡献步骤非常容易遵循。然而，我发现情况并不是这样，我能够利用我在 Go 方面的专业知识来帮助那些被困在各种意想不到的地方的人。事实证明，现实世界充满了边缘案例。例如，某人有两个 git 电子邮件，一个是个人邮件，另一个是工作邮件。在签署工作电子邮件的 CLA 时出现了延迟，所以他们尝试使用自己的个人电子邮件。这意味着每次提交都必须修改为使用正确的电子邮件，而工具没有考虑到这一点。(幸运的是，投稿指南中有一个疑难解答部分涵盖了这个确切的问题！)有些人还遇到了其他一些微妙的错误或环境配置错误，因为不止一次的 Go 安装有点不寻常。有时，必须显式地临时设置 GOROOT 环境变量，才能让 godoc 显示正确的标准库中的更改。

总体上，我监督了一些新的土拨鼠爱好者做出了他们的第一次 Go 贡献。他们发送 CLs，回复评论反馈，进行编辑，反复迭代，直到每个人都满意为止，最终看到他们的第一个 Go 贡献被合并到主分支中！当看到他们脸上的快乐会感觉非常值得，因为做出第一次贡献的喜悦是我可以与自己联系起来的。能够帮助他们并解释他们有时发现的棘手情况也是很棒的。据我所知，许多快乐的土拨鼠爱好者离开了这次活动，包括我自己！