提交者指南

本指南适用于在 ansible 和 ansible-collections GitHub 组织仓库中拥有提交权限的人员。

Ansible-core 的提交者必须是作为 Ansible Core 团队成员行动的 Red Hat 员工。Ansible collections 的提交者则是社区成员或 Ansible 工程团队成员。请在提交代码前阅读本指南。

这些指南适用于所有人。同时，这并不是一份流程文档。因此，请仅凭良好的判断力行事。你被授予提交权限是因为我们信任你的判断。

话虽如此，请谨慎地使用这份信任。

如果你滥用信任导致组件崩溃、构建失败等，信任等级将会下降，你可能会被要求停止提交或失去提交权限。

ansible-core 的特性、高层设计和路线图

作为核心团队成员，你是开发 路线图 团队不可或缺的一部分。请积极参与，并推动你希望看到的特性和修复。同时请记住，Red Hat 作为一家公司，会对各种版本的某些特性、修复、API 等做出承诺。Red Hat 公司和 Ansible 团队必须按计划完成并发布这些更改。对用户、社区和客户的义务必须放在首位。由于这些承诺，如果你想独立开发某个特性，但它会影响 Ansible 内部的大量其他部分，那么该特性可能无法进入某个发布版本。

任何其他新特性和高层设计的更改都应通过提案流程（待定），以确保社区和核心团队有机会审阅并批准该想法。核心团队对基于提案合并到 Ansible-core 的新特性负有唯一责任。

Ansible collections 的特性、高层设计和路线图

Collection 维护者定义 Collection 自身的特性、高层设计和路线图，并负责根据与社区讨论的提案将新特性合并到 Ansible collections 中。

我们在 GitHub 上的工作流程

作为一名提交者，你可能已经知道这一点，但我们的工作流程构成了许多团队策略。请确保你了解以下工作流程步骤：

  • 将你想要进行工作的仓库 Fork 到你自己的个人仓库中

  • 在需要提交代码的特定分支上工作

  • 向原仓库创建 Pull Request (PR)，并标记你希望审阅的人员；指派一名人员作为该 PR 的主要“负责人” (owner)

  • 根据提供的评论必要地调整代码

  • 请求该仓库的提交者进行最终审阅并合并

提交者工作流程补充说明：

核心团队意识到这个过程有时可能比较繁琐。有时，团队成员会通过直接提交或合并自己的 PR 来打破规则。本节是一套指南。如果你只是在更改文档中的一个逗号，或者进行非常微小的更改，你可以凭自己的判断行事。这同样是关于信任的问题。对于任何重大更改，该流程至关重要；但对于小事或需要快速完成的工作，请凭判断力行事，并确保团队成员了解你的工作。

Core 团队中的角色

  • 核心提交者 (Core committers)：大多数事项使用 PR 是可以的，但我们应该设定一个时间限制。对于悬而未决的 PR，可以根据这些开发者的判断进行合并。

  • 模块维护者 (Module maintainers)：模块维护者拥有特定模块的所有权，并通过当前的模块 PR 机制拥有间接提交权限。

  • Collection 维护者 (Collection maintainers)：Collection 维护者拥有特定 Collection 的所有权，并对其拥有提交权限。每个 Collection 可以设置自己的贡献规则。

通用规则

拥有直接提交权限的人员被授予了可以执行各种操作的权力——可能多到我们无法全部写下来。不要将这些视为死板的规则，而应将其视为通用指南，拥有此权力的人员应凭最佳判断力行事。

  • 不要 (Do NOT)

    • 直接提交代码。

    • 合并你自己的 PR。其他人应该有机会审阅并批准 PR 的合并。如果你是核心提交者，对于非常微小的更改，你拥有少量的自由裁量权。

    • 忽视替代环境。考虑其他可能性——是的，有些人的环境很糟糕，但他们正是最需要我们帮助的人。

    • 拖累你的社区团队成员。在你审阅任何 PR 时，讨论其技术优点。避免负面情绪和人身攻击。关于如何成为一名优秀的社区成员，请阅读我们的 社区行为准则。

    • 忽视维护负担。维护成本过高的特性可能不值得添加。

    • 破坏 Playbook。始终牢记向后兼容性。

    • 忘记保持简单。复杂性会滋生各种问题。

  • 要 (Do)

    • 使用 Squash，尽可能避免合并提交，必要时使用 GitHub 的 squash commits 或 cherry-pick（这对 bisect 调试很有帮助）。

    • 保持活跃。在项目中没有活动（通过合并、分拣/triage、提交等）的提交者将被暂停权限。

    • 考虑向后兼容性（参见“不要破坏现有 Playbook”）。

    • 编写 测试 并确保你审阅的他人的 PR 得到了良好的测试覆盖。带有测试的 PR 比那些应该包含测试但没有包含测试的 PR 具有更高的优先级。虽然并非所有更改都需要测试，但请确保为新特性、错误修复和功能更改添加测试。

    • 与其他提交者讨论，特别是当你对某些事情不确定时。

    • 编写文档！如果你的 PR 是一个新特性或行为更改，请确保你更新了所有相关的文档，或已通知相关人员进行更新。此外，添加该文档所兼容的 ansible-core 或 collection 版本也会有所帮助（以避免稳定版文档与开发版文档之间的混淆，以及确保向后兼容性等）。

    • 考虑作用域，有时一个修复可以被泛化。

    • 保持简单，这样事物才是可维护的、可调试的且易于理解的。

提交者应继续遵守 Ansible 社区其他成员所遵循的相同社区和贡献指南。