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 贡献被合并到主分支中！当看到他们脸上的快乐会感觉非常值得，因为做出第一次贡献的喜悦是我可以与自己联系起来的。能够帮助他们并解释他们有时发现的棘手情况也是很棒的。据我所知，许多快乐的土拨鼠爱好者离开了这次活动，包括我自己！