本文已超过一年。较旧的文章可能包含过时内容。请检查页面中的信息自发布以来是否仍正确。

贡献开发指南

一位新贡献者描述了编写并向 Kubernetes 开发指南提交更改的经历。

当大多数人想到为开源项目做贡献时,我猜他们想到的可能是贡献代码更改、新功能和 Bug 修复。作为一名软件工程师和长期的开源用户及贡献者,我当然也是这么想的。虽然我在不同的工作流程中写过不少文档,但 Kubernetes 社区庞大的规模对我来说是一种全新的“客户”。当 Google 要求我和我的同事在 Lion's Way 对 Kubernetes 开发指南进行急需的更新时,我完全不知道会发生什么。

本文最初发表在Kubernetes 贡献者社区博客上。

与社区合作的乐趣

作为专业撰稿人,我们习惯于受雇撰写非常具体的文章。我们专注于技术服务和产品的营销、培训和文档编写,内容范围从相对轻松的营销邮件到面向 IT 和开发人员的深度技术白皮书。对于这类专业服务,每个交付成果往往都有可衡量的投资回报。我知道在处理开源文档时不会存在这个指标,但我无法预测它会如何改变我与项目的关系。

我们的写作与传统客户之间关系的主要特点之一是,我们在公司内部总有一到两个主要的联系点。这些联系人负责审查我们的写作,确保其与公司风格一致,并针对他们期望的受众。这可能会带来压力——这就是为什么我很高兴我的写作搭档、目光敏锐的审阅者和“嗜血”编辑 Joel 负责处理大部分客户联系工作。

与 Kubernetes 社区合作时,让我惊讶和高兴的是,所有与客户联系的压力都消失了。

“我需要多么小心翼翼?如果我搞砸了怎么办?如果我惹怒了开发者怎么办?如果我树敌怎么办?”当我第一次加入 Kubernetes Slack 上的 #sig-contribex 频道并宣布我将着手处理开发指南时,所有这些问题都在我脑海中飞速闪过,让我感觉如履薄冰。

“Kubernetes 行为准则生效中,请大家友善待人。”——Jorge Castro,SIG ContribEx 联合主席

我的担忧是多余的。我立刻感到受欢迎。我愿意相信这不仅仅是因为我正在做一项非常需要的任务,更是因为 Kubernetes 社区充满了友好、热情的人们。在每周的 SIG ContribEx 会议上,我们关于开发指南进展的报告立即被纳入讨论。此外,会议主持人总是强调Kubernetes 行为准则正在生效,并且我们应该,就像 Bill 和 Ted 一样,友善待人。

但这并不意味着一切都很容易

开发指南需要一次相当彻底的修订。当我们着手处理它时,它已经包含了大量信息和新开发者需要执行的许多步骤,但随着时间的推移和疏于维护,它已经有些陈旧了。文档确实需要全局性的审视,而不仅仅是零星的修复。结果,我最终向 Community repo 提交了一个巨大的拉取请求:增加了 267 行,删除了 88 行。

拉取请求的生命周期需要一定数量的 Kubernetes 组织成员在合并之前进行审查和批准更改。这是一个很好的实践,因为它可以使文档和代码都保持良好的状态,但说服合适的人花时间进行如此繁重的审查可能会很困难。因此,这个巨大的 PR 从我首次提交到最终合并花了 26 天。但最终,它成功了

由于 Kubernetes 是一个发展相当迅速的项目,而且开发者通常对编写文档并不那么热情,我还遇到了一个问题,那就是有时描述 Kubernetes 子系统工作原理的秘密宝藏深藏在一位杰出工程师迷宫般的思维中,而不是用简单的英语写在 Markdown 文件里。当需要更新端到端 (e2e) 测试的入门文档时,我一头扎进了这个问题。

我这段旅程让我走出了文档写作领域,进入了使用未完成软件的新用户角色。我最终与新的 kubetest2 框架的开发者之一合作,记录了进行 e2e 测试的最新上手流程,但这需要我花很多时间挠头思考。您可以查看我已完成的拉取请求来亲自评判结果。

没人是老板,人人提供反馈

然而,尽管我暗自预料会是一片混乱,但为 Kubernetes 开发指南做贡献以及与出色的 Kubernetes 社区互动的过程却异常顺利。没有争论。我没有树敌。每个人都非常友好和热情。这是一段令人愉快的经历。

对于开源项目,没有一个单一的老板。庞大无比的 Kubernetes 项目被划分为许多不同的特别兴趣小组 (SIG)、工作组和社区。每个小组都有自己的定期会议、指定的职责和选举产生的主席。我的工作与 SIG ContribEx(负责监督和改进贡献者体验)和 SIG Testing(负责测试)的努力都有交集。这两个 SIG 都证明很容易合作,渴望获得贡献,并且成员都非常友好和热情。

在一个像 Kubernetes 这样活跃、有生命力的项目中,文档需要与代码库一同持续进行维护、修订和测试。开发指南将继续对新贡献者加入 Kubernetes 代码库至关重要,正如我们的努力所表明的,确保这份指南与 Kubernetes 项目的演进保持同步至关重要。

Joel 和我非常享受与 Kubernetes 社区的互动以及为开发指南做贡献。我非常期待不仅继续贡献更多内容,还期待继续深化过去几个月在这个广阔的开源社区中建立的新友谊。