收集 PR 的审查清单

使用此部分作为清单提醒，提醒你在审查集合 PR 时要审查的项目。

审查错误报告

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

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

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

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

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

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

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

审查建议的更改

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

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

  • 带来比价值更多的伤害。

  • 引入非幂等解决方案。

  • 复制已有的功能（在集合内部或外部）。

  • 违反 Ansible 开发约定.

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

  • 拉取请求 MUST NOT 包含混合的错误修复和与之无关的新功能。如果是，请要求作者将拉取请求拆分为单独的 PR。

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

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

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

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

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

  • 更改必须遵循 Ansible 文档标准 和 Ansible 文档风格指南。

  • 更改必须遵循 开发约定。

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

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

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

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

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

  • FQCN 必须用于 extends_documentation_fragment:，除非作者引用的是来自 ansible-core 的 doc_fragments。

  • 新功能必须在 EXAMPLES 块 中有相应的示例。

  • 返回值必须在 RETURN 块 中记录。

审查 PR 中的测试

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

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

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

  • 集成测试必须涵盖 check_mode（如果支持）。

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

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

审查合并提交和破坏性更改

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

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