集合 PR 代码审查清单

将本节用作审查集合 PR 时需要审查项目的清单提醒。

审查错误报告

当用户报告错误时，请验证所报告的行为。请记住，始终以友好的方式提供反馈。

  • 用户在“复现步骤”问题部分输入的代码中是否犯了错误？我们经常看到将用户错误报告为错误的情况。

  • 用户是否假设了意外行为？确保相关文档清晰明了。如果文档不明确，则此问题有助于我们改进文档。

  • 是否有最小的可复现示例？如果没有，请要求报告者降低复杂性，以帮助查明问题。

  • 此问题是否是环境配置错误导致的结果？

  • 如果似乎是真正的错误，则该行为在最新版本或开发分支中是否仍然存在？

  • 复现错误，或者如果您没有合适的架构，请要求其他贡献者复现错误。

审查建议的更改

审查 PR 时，请验证建议的更改不会：

  • 不必要地破坏向后兼容性。

  • 弊大于利。

  • 引入非幂等解决方案。

  • 重复已存在的特性（集合内或集合外）。

  • 违反Ansible 开发约定。

需要检查的 PR 中的其他标准包括：

  • 拉取请求中**不能**混合包含错误修复和与之关系不密切的新功能。如果是这种情况，请要求作者将拉取请求拆分为单独的 PR。

  • 如果拉取请求不是文档修复，则必须包含变更日志片段。仔细检查格式，如下所示：

  • 新的模块和插件（非 jinja2 过滤器和测试插件）不需要变更日志片段。

  • 对于 jinja2 过滤器和测试插件，请查看变更日志片段的特殊语法。

  • 变更日志内容包含对集合最终用户的有用信息。

  • 如果使用拉取请求添加了新文件，则它们遵循集合许可要求。

  • 更改遵循Ansible 文档标准和Ansible 文档样式指南。

  • 更改遵循开发约定。

  • 如果添加了新的插件，则它是允许的插件类型之一。

  • 文档、示例和返回值部分使用模块的M(..)格式宏的 FQCN。

  • 来自 ansible-core 的模块和插件在提及时使用ansible.builtin.作为 FQCN 前缀。

  • 添加新的选项、模块、插件或返回值时，相应的文档或返回值部分使用包含其首次发布的*集合*版本的version_added:。

  • 这通常是下一个次要版本，有时是下一个主要版本。(例如：如果当前版本是 2.7.5，则下一个次要版本将是 2.8.0，下一个主要版本将是 3.0.0)。

  • 除非作者指的是来自 ansible-core 的 doc_fragments，否则extends_documentation_fragment: 使用 FQCN。

  • 新功能在示例块中具有相应的示例。

  • 返回值在返回块中进行了说明。

审查 PR 中的测试

如果测试适用于 PR 中包含的更改并且可以实施，请审查以下内容：

  • 在适用的情况下，拉取请求具有集成测试和单元测试。

  • 涵盖所有更改。例如，错误案例或新选项分别以及与其他选项的合理组合。

  • 如果支持，集成测试涵盖check_mode。

  • 集成测试检查系统的实际状态，而不仅仅是模块报告的内容。例如，如果模块实际更改了文件，请使用ansible.builtin.stat模块检查文件是否已更改。

  • 集成测试检查返回值（如果适用）。

审查合并提交和重大更改

  • 拉取请求不包含合并提交。请参阅拉取请求底部的 GitHub 警告。如果存在合并提交，请要求作者重新设置拉取请求分支的基础。

  • 如果拉取请求包含重大更改，请询问作者和集合维护者是否确实需要这些更改，以及是否有办法避免引入重大更改。如果存在重大更改，则它们**必须**仅出现在下一个主要版本中，而**不能**出现在次要版本或补丁版本中。唯一的例外是由于绝对必要的安全修复导致的重大更改，以修复安全问题。