收集 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）。

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

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

  • 返回值在 RETURN 块 中有文档。

审查 PR 中的测试

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

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

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

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

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

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

审查合并提交和重大更改

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

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