贡献

Kubeflow 贡献指南

本文档是贡献代码库的唯一权威来源。我们非常欢迎您为本项目提交补丁和贡献。您只需遵循一些简单的指南。

入门

签署你的提交

Kubeflow 使用开发者原创证书 (DCO)。

请查阅 https://github.com/kubeflow/community/tree/master/dco-signoff-hook#signing-off-commits 了解如何签署您的贡献。

遵守行为准则

请务必阅读并遵守我们的行为准则和包容性文档。

成员资格

关于不同类型的 Kubeflow 成员以及成员资格标准的详细信息，请参见社区成员资格

注意：任何人都可以为 Kubeflow 贡献，加入 Kubeflow 组织不是强制步骤。

公司/组织

如果您希望您的公司或组织因对 Kubeflow 的贡献或参与社区（包括作为用户）而获得认可，请发送一个 PR，将相关信息添加到 member_organizations.yaml。

此外，如果您的公司在内部采用了 Kubeflow，我们鼓励您将自己添加到 ADOPTERS.md！

如果您希望将您员工的 GitHub 贡献归因于您的公司，请让他们在其 GitHub 个人资料中设置公司字段。

你的首次贡献

寻找工作内容

随时欢迎提供帮助！例如，文档（就像您现在阅读的文字）总是可以改进。总有代码可以澄清，变量或函数可以重命名或添加注释。总有需要更多测试覆盖的地方。您明白我的意思了——如果您看到任何您认为应该修复的地方，您就应该负责。以下是入门方法。

入门问题

寻找适合入门的 Kubeflow 问题

OWNERS 文件和 PR 工作流

我们的 PR 工作流程与 Kubernetes 的几乎完全相同。这些说明大部分是 Kubernetes 贡献者和OWNERS 文件使用说明的修改版本。

OWNERS 文件概览

OWNERS 文件用于指定对 Kubeflow 代码库不同部分的责任。目前，我们使用它们来分配在两阶段代码审查流程中使用的审查者 (reviewer) 和批准者 (approver) 角色。我们的 OWNERS 文件灵感来自Chromium OWNERS 文件，后者又启发了GitHub 的 CODEOWNERS 文件。

使用代码审查的项目的进度受限于能够审查代码的人数。个人代码审查的质量受限于他们对正在审查的代码的熟悉程度。我们的目标是通过审慎使用和维护 OWNERS 文件来解决这两个问题。

OWNERS

每个包含独立代码或内容单元的目录也可能包含一个 OWNERS 文件。此文件适用于该目录内的所有内容，包括 OWNERS 文件本身、同级文件和子目录。

OWNERS 文件采用 YAML 格式，支持以下键

  • approvers：可以 /approve PR 的 GitHub 用户名或别名列表
  • labels：自动应用于 PR 的 GitHub 标签列表
  • options：解释此 OWNERS 文件的方式选项映射，目前只有一个
    • no_parent_owners：如果不存在，默认为 false；如果为 true，则排除父级 OWNERS 文件。允许 a/deep/nested/OWNERS 文件阻止 a/OWNERS 文件对 a/deep/nested/bit/of/code 产生任何影响的情况。
  • reviewers：适合 /lgtm PR 的 GitHub 用户名或别名列表
  • emeritus_approvers：之前在 approvers 部分但不再积极批准代码的 GitHub 用户名列表。请参见下文了解更多详情。

所有用户都应可被指派。在 GitHub 术语中，这意味着他们要么是仓库的合作者，要么是该仓库所属组织的成员。

典型的 OWNERS 文件如下所示

approvers:
  - alice
  - bob # this is a comment
reviewers:
  - alice
  - carol # this is another comment
  - sig-foo # this is an alias

荣誉成员 (Emeritus)

这是不可避免的，有时人们可能会转移重心、更换工作或暂时离开项目中的特定领域。这些人在代码库的某些领域可能是领域专家，但无法再投入必要的时间来履行审查和批准变更的职责。鼓励他们将自己作为“荣誉”批准者添加到 emeritus_approvers 键下。

emeritus_approvers 键下方的 GitHub 用户名不能再批准代码（使用 /approve 命令），并且 prow 在指派时会忽略他们。但是，查看 OWNERS 文件的人仍然可以参考他们，以获得可能的第二意见或更具参考价值的意见。

当贡献者在该领域变得更加活跃时，他们可以根据现有批准者的判断，被晋升回常规批准者。

emeritus_approvers:
  - david
  - emily

OWNERS_ALIASES

每个仓库的根目录都可能包含一个 OWNERS_ALIAS 文件。

OWNERS_ALIAS 文件采用 YAML 格式，支持以下键

  • aliases：别名到 GitHub 用户名列表的映射

我们使用别名来表示组，而不是 GitHub Teams，因为 GitHub Teams 的更改无法公开审计。

OWNERS_ALIASES 文件示例如下

aliases:
  sig-foo:
    - david
    - erin
  sig-bar:
    - bob
    - frank

OWNERS 文件中列出的 GitHub 用户名和别名不区分大小写。

代码审查流程

  • 作者 (author) 提交 PR

  • 阶段 0：自动化为 PR 建议审查者 (reviewer) 和批准者 (approver)

    • 确定最接近被更改代码的 OWNERS 文件集合
    • 选择至少两名建议的审查者 (reviewer)，尝试为每个叶子 OWNERS 文件找到一个唯一的审查者，并请求他们在 PR 上进行审查
    • 选择建议的批准者 (approver)，每个 OWNERS 文件中选择一位，并在 PR 的评论中列出他们

  • 阶段 1：人工审查 PR

    • 审查者 (reviewer) 查看整体代码质量、正确性、合理的软件工程实践、风格等。
    • 组织内的任何人都可作为审查者 (reviewer)，但开启 PR 的个人除外
    • 如果代码变更对他们来说看起来不错，审查者 (reviewer) 在 PR 评论或审查中输入 /lgtm；如果他们改变主意，则输入 /lgtm cancel
    • 一旦审查者 (reviewer) 输入了 /lgtm，prow (@k8s-ci-robot) 会为 PR 应用一个 lgtm 标签

  • 阶段 2：人工批准 PR

    • PR 作者 (author) 使用 /assign 将所有建议的批准者 (approver) 分配给 PR，并可选择性地通知他们（例如：“ping @foo 等待批准”）
    • 只有在相关 OWNERS 文件中直接或通过别名列出的人员，包括开启 PR 的个人，才能作为批准者 (approver)
    • 批准者 (approver) 查看整体接受标准，包括与其他功能的依赖关系、向前/向后兼容性、API 和标志定义等
    • 如果代码变更对他们来说看起来不错，批准者 (approver) 在 PR 评论或审查中输入 /approve；如果他们改变主意，则输入 /approve cancel
    • prow (@k8s-ci-robot) 更新其在 PR 中的评论，指示哪些批准者 (approver) 仍需要批准
    • 一旦所有批准者 (approver)（来自每个先前确定的 OWNERS 文件中的一位）都已批准，prow (@k8s-ci-robot) 会应用一个 approved 标签

  • 阶段 3：自动化合并 PR

    • 如果以下所有条件都为真

      • 所有必需的标签都存在（例如：lgtm, approved）
      • 所有阻塞性标签都不存在（例如：没有 do-not-merge/hold, needs-rebase）

    • 并且如果以下任何条件为真

      • 此仓库没有配置预提交 prow 作业
      • 此仓库配置了预提交 prow 作业，并且在自动重新运行最后一次后都通过了

    • 则 PR 将自动合并

流程的怪异之处

我们观察到一些行为，虽然可能，但不鼓励这样做，因为它们违背了此审查流程的初衷。其中一些将来可能会被阻止，但这反映了目前的状况。

  • 批准者 (approver) 的 /lgtm 同时被解释为 /approve
    • 虽然对某些人来说是一个方便的捷径，但同一个命令根据评论者身份不同而被解释为两种方式之一，这可能令人惊讶
    • 相反，请明确写出 /lgtm 和 /approve 以帮助观察者，或者将 /lgtm 留给审查者 (reviewer)
    • 这与至少有两个人在 PR 上进行审查的理念相悖，并且可能表明审查者 (reviewer)（同时不是批准者 (approver)）数量过少
  • 技术上讲，任何 Kubeflow GitHub 组织的成员都可以随意地 /lgtm 一个 PR
    • 鼓励非成员进行随意审查，以此展示经验并表达成为合作者或审查者的意愿
    • 成员随意 /lgtm 可能表明我们的 OWNERS 文件范围过小，或者现有审查者 (reviewer) 的响应速度太慢
    • 这与一开始就指定审查者 (reviewer) 的理念相悖，因为指定审查者是为了确保作者 (author) 能够从熟悉代码的人那里获得可操作的反馈
  • 审查者 (reviewer) 和批准者 (approver) 响应迟缓
    • 这会给作者 (author) 带来很多沮丧，他们通常不知道为什么他们的 PR 被忽略了
    • 许多审查者 (reviewer) 和批准者 (approver) 的 GitHub 通知过多，@提及可能无法获得快速响应
    • 如果作者 (author) /assign 一个 PR，审查者 (reviewer) 和批准者 (approver) 会在他们的 PR 仪表盘上知晓
    • 作者 (author) 可以通过手动阅读相关的 OWNERS 文件，/unassign 掉无响应的人，然后 /assign 给其他人来解决这个问题
    • 这表明我们的 OWNERS 文件过时了；精简审查者 (reviewer) 和批准者 (approver) 列表会有所帮助
    • PR 作者 (author) 有责任推动 PR 得到解决。这意味着如果 PR 审查者 (reviewer) 没有响应，他们应该按如下所述进行升级
      • 例如，及时 ping 审查者 (reviewer) 以获得审查
      • 如果审查者 (reviewer) 没有响应，请查看根目录下的 OWNERs 文件并 ping 那里列出的批准者 (approver)
  • 作者 (author) 响应迟缓
    • 这会耗费大量注意力，因为单个 PR 的上下文会随着时间丢失
    • 这会损害项目整体，因为其总体噪声水平会随着时间增加
    • 相反，关闭长时间未触及的 PR（我们目前有一个机器人会在 90 天后执行此操作）

使用 OWNERS 文件自动化

prow

Prow 接收来自 GitHub 的事件并对其做出反应。它实际上是无状态的。以下 prow 组件用于实现上述代码审查流程。

  • 命令: tide
    • 每个仓库的配置
      • labels：合并所需标签列表（例如：lgtm）
      • missingLabels：合并所需缺失标签列表（例如：do-not-merge/hold）
      • reviewApprovedRequired：默认为 false；为 true 时，要求合并前必须至少有一个已批准的拉取请求审查
      • merge_method：默认为 merge；当为 squash 或 rebase 时，在点击 PR 的合并按钮时改用该合并方法
    • 当 PR 满足上述配置的适当条件时，会合并 PR
    • 如果 PR 针对的仓库有任何预提交 prow 作业，它们将在合并前最后一次重新运行
  • 插件: assign
    • 响应 PR 中的 /assign 评论来指派 GitHub 用户
    • 响应 PR 中的 /unassign 评论来取消指派 GitHub 用户
  • 插件: approve
    • 每个仓库的配置
      • issue_required：默认为 false；为 true 时，要求 PR 描述链接到一个 issue，或者至少有一位批准者 (approver) 发出 /approve no-issue 命令
      • implicit_self_approve：默认为 false；为 true 时，如果 PR 作者在相关的 OWNERS 文件中，则视为他们已隐式 /approve
    • 一旦每个所需 OWNERS 文件中的一位批准者 (approver) 都已 /approve，则添加 approved 标签
    • 在满足所需 OWNERS 文件时添加评论
    • 移除过时的批准状态评论
  • 插件: blunderbuss
    • 确定审查者 (reviewer) 并请求他们在 PR 上进行审查
  • 插件: lgtm
    • 当审查者 (reviewer) 在 PR 上评论 /lgtm 时，添加 lgtm 标签
    • PR 作者 (author) 不得 /lgtm 自己的 PR
  • 包: k8s.io/test-infra/prow/repoowners
    • 解析 OWNERS 和 OWNERS_ALIAS 文件
    • 如果遇到 no_parent_owners 选项，则父级 owner 不会对其当前 OWNERS 文件相邻或下方的文件产生任何影响

维护 OWNERS 文件

OWNERS 文件应定期维护。

我们鼓励人们通过 PR 自荐或自愿从 OWNERS 文件中移除。理想情况下，未来我们可以使用指标驱动的自动化来协助这一过程。

我们应该努力

  • 增加 OWNERS 文件数量
  • 在 OWNERS 文件中添加新人
  • 确保 OWNERS 文件只包含组织成员和仓库合作者
  • 确保 OWNERS 文件只包含积极贡献或审查其负责代码的人员
  • 从 OWNERS 文件中移除不活跃的人员

OWNERS 使用不良示例

  • 缺少 OWNERS 文件导致过多命中根目录 OWNERS 的目录
  • 拥有同一人作为批准者和审查者的 OWNERS 文件
  • 超过 6 个月未更新的 OWNERS 文件
  • 包含非合作者的 OWNERS 文件

OWNERS 使用良好示例

  • reviewers 多于 approvers
  • approvers 不在 reviewers 部分
  • 定期更新的 OWNERS 文件（至少每个版本更新一次）

反馈

此页有用吗？


上次修改日期：2025年2月11日：trainer: Initial Documentation for Kubeflow Trainer V2 (#3958) (10b7063)