集合 PR 代码审查清单

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

审查错误报告

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

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

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

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

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

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

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

审查建议的更改

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

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

  • 弊大于利。

  • 引入非幂等解决方案。

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

  • 违反Ansible 开发约定。

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

  • 拉取请求中**不得**混合包含与新特性不紧密相关的错误修复和新特性。如果是这样，请请求作者将拉取请求拆分为单独的 PR。

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

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

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

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

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

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

  • 更改遵循开发约定。

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

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

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

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

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

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

  • 新特性在EXAMPLES 块中具有相应的示例。

  • 返回值在RETURN 块中记录。

审查 PR 中的测试

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

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

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

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

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

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

审查合并提交和重大更改

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

  • 如果拉取请求包含重大更改，请询问作者和集合维护者这是否真的需要，以及是否存在不引入重大更改的方法。如果存在重大更改，则它们**必须**仅出现在下一个主要版本中，并且**不得**出现在次要或修补程序版本中。唯一的例外是由绝对必要的安全修复程序引起的重大更改，以修复安全问题。