Ansible 社区软件包集合要求

概述

本文档描述了包含在 Ansible 社区软件包中的 Ansible 社区集合维护者的要求。所有候选集合和已包含的集合都必须满足本文档中标有MUST的标准。

您还可以在集合包含标准检查清单中找到这些要求。

每个被拒绝的候选者都将根据在专用社区主题中做出的决定，收到来自Ansible 社区指导委员会的反馈。

反馈和沟通

非常欢迎任何反馈和帮助。请创建一个社区主题或将您的问题带到社区会议。

保持知情

要跟踪影响集合的更改

沟通和工作组

论坛概述

论坛是我们异步的默认沟通平台。

在组织围绕 Ansible 集合的沟通方面，您需要了解以下概念

  • 标签：与类别一起，标签是论坛中用于围绕特定主题组织对话的主要功能。大多数 Ansible 项目都有一个或多个关联标签。对于 Ansible 集合，主要标签名称通常是集合目标的技术：例如，kubernetes.core 使用 kubernetes 标签，ansible.windows 使用 windows 标签，community.postgresql 使用 postgresql 标签。

  • 论坛组：组允许您组织用户、管理权限、拥有提供相关信息的团队页面、自动订阅成员的标签、提及或向整个组发送消息等等。一个集合工作组的示例是PostgreSQL Ansible 集合工作组。

有关更多详细信息，请参阅工作组 - 您可以请求的事项！论坛主题。

沟通要求

您的集合

  • 必须在论坛中拥有相应的公共标签，或者至少重用一个现有标签。

    • 如果多个集合涵盖类似主题，则可以共享一个标签；例如，amazon.aws 和 community.aws 都可以使用 aws 标签。

    • 此外，集合可以请求一个论坛组。如果集合请求或已拥有一个组

      • 所有相关标签都必须与该组关联。加入该组的每个人都会自动订阅这些标签。

      • 该组必须是公开的，并且任何论坛用户都可以自由加入。

    • 使用请求标签/论坛组主题来请求标签和论坛组。

  • 其 README 中必须包含一个沟通部分，其中包含对论坛的引用，类似于collection_template README.md。

    • 该部分必须至少包含对获取帮助论坛类别的引用，可能包括 URL 中的标签。

    • 该部分必须包含参与者应使用哪些标签进行与集合相关的主题的信息。

    • 如果集合有论坛组，则该部分必须包含对该组的引用。

    • 引用的描述必须欢迎读者加入和参与。

    • 集合维护者应该订阅所有关联的标签并成为所有关联组的成员。

  • 应该禁用 GitHub 的Discussions功能，以支持论坛。

集合基础设施

以下指南描述了集合所需的基础设施

  • 必须拥有一个公开可用的问题跟踪器，该跟踪器不需要付费的服务级别即可创建帐户以及创建和查看问题。

  • 必须在其代码库中启用问题功能，并接受任何人的问题报告。

  • 必须拥有与社区行为准则兼容的行为准则 (CoC)。

  • 必须发布到版本 1.0.0 或更高版本的Ansible Galaxy。

  • 必须仅包含遵循许可规则的对象。

  • 不应包含任何与当前 Galaxy tarball 大小限制 20 MB 相比较大的对象（二进制文件），例如，不要包含用于测试目的的软件包安装程序。

  • 不应包含任何不必要的文件，例如临时文件。

Python 兼容性

除了本节中指定的 Python 要求外，集合还应遵守ansible-and-python-3中的提示。

Python 要求

集合的 Python 要求在**控制器环境**和**其他环境**之间有所不同。

控制器环境

  • 除非必需的库不支持这些 Python 版本，否则集合**必须**支持控制器环境中所有符合条件的控制器 Python 版本。 指导委员会可以根据具体情况授予其他例外。

    • 控制器环境：插件/模块始终在与 ansible-core 本身相同的环境（Python 解释器、venv、主机等）中运行。

    • 符合条件的控制器 Python 版本：至少一个集合支持的 ansible-core 版本在控制器端支持的 Python 版本。符合条件的版本可以从ansible-core 支持矩阵和集合中meta/runtime.yml中的requires_ansible值确定。

  • 集合**必须**记录控制器环境中**不支持**的所有符合条件的控制器 Python 版本。详情请参阅Python 文档要求。

其他环境

  • 除非必需的库不支持这些 Python 版本，否则集合**必须**支持其他环境中所有符合条件的控制器 Python 版本。 指导委员会可以根据具体情况授予其他例外。

    • 其他环境：插件/模块不在控制器环境中运行。

    • 符合条件的目标 Python 版本：至少一个集合支持的 ansible-core 版本在目标端支持的 Python 版本。符合条件的版本可以从ansible-core 支持矩阵和集合中meta/runtime.yml中的requires_ansible值确定。

  • 集合**必须**记录其他环境中不支持的所有符合条件的目标 Python 版本。详情请参阅Python 文档要求。

停止支持 Python 版本

由于停止对现有模块/插件的 Python 版本的支持属于重大更改，因此集合

  • **应该**在停止支持之前，在其旧版本的变更日志的已弃用功能部分中宣布。

  • **必须**发布一个实际停止支持的重大版本。

Python 文档要求

  • 如果您的集合不支持所有符合条件的控制器/目标 Python 版本，则**必须**在 README 中记录其支持的版本。

  • 如果您的集合的大部分与 ansible-core 支持相同的 Python 版本，但某些模块和插件不支持，则**必须**在这些模块和插件的文档中包含支持的 Python 版本。

模块和插件实用程序的开发标准

  • module_utils 和 plugin_utils 可以标记为仅供集合内部使用，但**必须**记录这一点，并且**必须**使用下划线作为文件名开头。

    • 如果您将 module_utils 中的实用程序从公共更改为私有，则您正在进行重大更改。如果您这样做，则必须发布集合的新主要版本。

  • 以下是 module_utils 文档的一些建议

    • 无文档字符串：我们推荐的 other-environment 的所有内容都受支持。

    • 文档字符串 'Python versions supported: same as for controller-environment'：我们推荐的 controller-environment 的所有内容都受支持。

    • 包含特定版本的文档字符串：'Python versions supported: '。

仓库结构要求

galaxy.yml

  • **必须**设置tags字段。

  • 集合依赖项**必须**符合一组规则。详情请参阅关于集合依赖项的部分。

  • 如果您计划拆分您的集合，则在较小的集合替换 Ansible 中的较大集合之前，**必须**批准新的集合。

  • 如果您计划添加其他集合作为依赖项，则**必须**通过正式的申请流程。

README.md

您的集合仓库**必须**在集合的根目录中包含一个README.md，请参阅collection_template/README.md以了解示例。

meta/runtime.yml

示例：meta/runtime.yml

  • meta/runtime.yml**必须**使用requires_ansible字段定义此集合工作的ansible-core的最低版本。例如，如果集合与 ansible-core 2.16 及更高版本一起使用，请在meta/runtime.yml文件中设置requires_ansible: '>=2.16'。

meta/execution-environment.yml

如果集合具有控制器端的 Python 包和/或系统包要求，为了方便执行环境构建，则**应该**在meta目录下的相应文件中列出这些要求，在meta/execution-environment.yml中指定，并验证。

有关更多信息，请参阅集合级依赖项指南，并以collection_template/meta目录内容为例。

模块和插件

  • 集合**必须**仅使用下面在plugins/目录中指定的目录，并且仅用于列出的用途

    ansible-core 识别的那些：

    doc_fragments、modules、module_utils、terminal，以及使用插件中列出的那些。可以通过查看https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/loader.py#L1126中每个*_loader的包参数的最后一个元素来验证此列表。

    plugin_utils：

    用于仅在控制器端使用、不在模块中使用的共享代码。

    sub_plugins：

    用于由集合内的插件而不是 ansible-core 管理的其他插件。我们使用子文件夹，这样当 ansible-core 添加新的插件类型时就不会发生冲突。

    核心团队（维护 ansible-core 的团队）已承诺不将这些目录用于任何与此处指定的用途冲突的用途。

其他目录

  • 集合**必须**不使用meta/、plugins/、roles/和playbooks/之外的任何插件、角色或剧本中可以通过 FQCN 调用、从其他集合使用或从用户剧本和角色中使用的文件。

    • 如果从已安装的集合中删除除这四个目录及其内容之外的所有文件或目录，则集合**必须**能够工作。

    • 内部插件、角色和剧本（仅在测试中使用，或仅用于发布集合，或仅用于某些其他内部目的，而不用于外部）不受此规则的约束，并且可能依赖于其他目录中的文件。

文档要求

集合

  • 必须使用链接和格式化宏。

  • 应在CONTRIBUTING.md或README.md文件中包含贡献者指南。

所有模块和插件

  • 必须包含文档块。

  • 必须包含示例块（除非与插件类型无关）。

  • 在集合内和集合外引用模块、插件和文档片段时，必须使用 FQCN，包括针对 ansible-core 使用ansible.builtin.。

  • 对于返回数据的模块和其他插件，必须包含返回块。

  • 向现有集合添加新内容时，必须包含version_added字段，例如，对于模块、插件、选项、返回值和属性。

    • 在创建新集合并进行首次发布之前，不必添加version_added。

    • version_added字段必须引用添加选项的集合版本，而不是 Ansible 或 ansible-core 的版本。

      • 如果出于某种原因，您需要指定 Ansible 或其他集合的版本号，则也必须提供version_added_collection: collection_name。我们强烈建议不要这样做。

贡献者工作流程

变更日志

  • 集合必须包含正确格式的变更日志。

    1. 您可以使用antsibull-changelog（文档）生成或检查变更日志，这为ansible包中包含的集合的变更日志提供一致性。

版本控制和弃用

  • 集合必须遵守语义版本控制约定

    • 必须在其集合根目录的README.md文件中包含此信息。

    • 应在其贡献者和维护者文档中包含此信息。

    • 必须在正确的类别下包含变更日志条目（Major changes、Minor changes、Bugfixes等）。

  • 集合必须保持向后兼容性。

    • 为了保持用户的向后兼容性，每个 Ansible 次要版本系列 (x.Y.z) 将使集合的主版本保持不变。

      • 例如，如果 Ansible 3.0.0 包含community.general 2.2.0，则每个 3.Y.z (3.1.z、3.2.z 等) 版本都将包含在构建时可用的最新community.general 2.y.z 版本。

      • Ansible 3.y.z **绝不会**包含community.general 3.y.z 版本，即使它可用。

      • 集合的主要版本更改将包含在下一个 Ansible 主要版本（在此示例中为 4.0.0）中。

      • 因此，请确保在生成新的 3.Y.Z 版本时，包含在 3.0.0 中的集合的当前主要版本至少能收到错误修复。

    • 由于包含了新的次要版本，您可以包含新的功能、模块和插件。您必须确保**不会**破坏向后兼容性！这意味着特别是

      • 您可以在patch releases中修复错误，但**不能**添加新功能或弃用内容。

      • 您可以在minor releases中添加新功能和弃用内容，但**不能**删除内容或更改现有功能的行为。

      • 您只能在major releases中删除内容或进行重大更改。

      • 有关更多信息，请参阅语义版本控制。

    • 我们建议您确保，如果在 Ansible 3.y.z 中包含的集合版本中添加了弃用，则删除本身只会发生在 Ansible 5.0.0 或更高版本中包含的集合版本中，而不是在 Ansible 4.0.0 中包含的集合版本中。

  • 集合应以某种方式向贡献者和用户提供其发布和弃用策略，例如在其 README 或固定问题中。请参阅community.general 中的公告作为示例。

命名

集合命名

为全新的命名空间选择名称时

  • 请考虑命名空间限制，其中列出了 Galaxy 中命名空间的要求。

  • 如果命名空间尚不存在且未被其他人占用，请提交命名空间请求以创建它。

命名建议

  • 对于ansible-collections GitHub 组织下的集合，存储库应命名为NAMESPACE.COLLECTION。

  • 对于为处理特定实体而创建的集合，它们应包含实体名称，例如community.mysql。

  • 对于公司维护的集合，存储库可以命名为COMPANY_NAME.PRODUCT_NAME，例如ibm.db2。

  • 避免使用过长的 FQCN/存储库名称

    • 尽量使其简洁明了。

    • 在NAMESPACE和COLLECTION部分中包含相同的单词/词组，例如my_system.my_system。

注意

如果您计划在**Red Hat Automation Hub**上获得集合认证，请通过ansiblepartners@redhat.com咨询 Red Hat 合作伙伴工程，以确保**Galaxy**上的社区集合与已认证集合之间的集合命名兼容性。

模块命名

  • 仅收集和返回信息的模块必须命名为<something>_info。

  • 收集和返回ansible_facts的模块必须命名为<something>_facts，并且**不得**返回任何非事实信息。

有关更多信息，请参阅模块开发指南。

集合许可要求

这些指南是包含在 Ansible 包中的策略，此外还包括可能影响您的代码的任何许可和法律问题。

注意

以下指南比严格必要的情况更为严格。一旦我们获得 Red Hat 法务部门的批准，我们将尝试添加更长的可接受许可证列表。

集合中有多种类型的內容，其许可必须以不同的方式进行处理。

  • 必须使用与GPL-3.0-或更高版本**兼容的**自由软件许可证进行许可的內容。

    • modules/目录内容。

    • module_utils/目录内容：ansible-core 通常使用BSD-2-条款许可证，允许第三方模块在第三方模块具有与 GPLv3 不兼容的许可证的情况下使用module_utils。在许可您自己的module_utils时，请考虑此用例。

    • plugins/之外的代码：如果它不导入GPL-3.0-or-later许可的代码，则可以使用与GPL-3.0-or-later兼容的其他许可证。

    • 非代码内容。

    • 为了被允许，许可证必须被认为是开源的，并且在**两者**上都与GPL-3.0-or-later兼容

  • 必须使用GPL-3.0-或更高版本许可的内容。

    • plugins/目录下的所有其他代码，modules/和module_utils/目录下的代码除外（参见上文）：这些插件在Ansible控制器进程内运行，该进程使用GPL-3.0-or-later许可，并且经常需要导入来自控制器的代码。由于这些原因，必须使用GPL-3.0-or-later。

    • plugins/目录外的代码：如果它导入了任何其他使用GPL-3.0-or-later许可的代码。请注意，这尤其适用于单元测试，这些测试通常会导入来自ansible-core、plugins/、module_utils/或modules/的代码，并且此类代码通常使用GPL-3.0-or-later许可。

贡献者许可协议

集合不得要求社区贡献者签署任何类型的贡献者许可协议 (CLA)，而只能签署开发者来源证书 (DCO)或类似的协议，这些协议只需要确认贡献的来源。这一要求旨在维护社区对其贡献的所有权，防止当一个实体拥有整个项目的版权时可能发生的意外许可变更，并降低贡献的门槛。

仓库管理

  • 每个集合都必须有一个公共 Git 仓库。

  • 集合的发布必须在其仓库中进行标记。

    • 必须使用带有tag参数的git实用程序来标记发布。

    • 标签名称必须与 Galaxy 版本号完全匹配。

    • 标签名称可以有v前缀。

    • 标签名称必须从一个版本到另一个版本保持一致的格式。

  • 发布到 Galaxy 的集合工件必须根据在其集合的 Git 仓库中作为该版本标记的源代码构建。

    • 构建过程中所做的任何更改都必须有清晰的文档说明，以便可以重现集合工件。

分支名称和配置

注意

本小节仅适用于ansible-collections下的仓库！其他集合仓库也可以遵循这些指南，但不是必须的。

  • 所有新的仓库都必须将main作为默认分支。

  • 拉取请求设置必须不允许merge commits。

  • 以下分支保护规则必须为所有发布分支启用

    • Require linear history

    • Do not allow bypassing the above settings

CI 测试

注意

您可以从collection_template仓库复制免费使用的GitHub action 工作流文件到您集合中的.github/workflows目录，以通过GitHub actions设置测试。该工作流涵盖了以下所有要求。

及时添加新的ansible-core版本，并考虑停止支持和测试其已结束生命周期 (EOL) 的版本以及您的集合不支持的版本。

如果您的集合仓库位于ansible-collections GitHub 组织下，请记住，测试作业的数量是有限的，并且在组织中的所有集合之间共享。因此，请关注集合的良好测试覆盖率，避免对不必要的实体（例如您的集合不支持的ansible-core EOL 版本）进行测试。

为了接收可能影响集合的重要公告（例如，测试），集合维护者应该

  • 订阅news-for-maintainers仓库。

  • 加入集合维护者和贡献者论坛组。

  • 您必须从最新的稳定ansible-base/ansible-core分支运行ansible-test sanity命令。

    • 集合必须运行等效于ansible-test sanity --docker的命令。

      • 如果他们不使用--docker，他们必须确保所有测试都运行，特别是编译和导入测试（应该为所有支持的Python版本运行）。

      • 集合可以选择跳过他们明确不支持的某些 Python 版本；这需要在README.md和每个模块和插件中进行记录（提示：使用文档片段）。但是，我们强烈建议您阅读Ansible Python 兼容性部分以了解更多详细信息。

  • 您还应该从ansible/ansible的devel分支运行ansible-test sanity，以便您可以尽早了解新的代码风格要求。

  • 健全性测试必须通过。

    • 您应该避免向test/sanity/ignore*.txt文件添加条目以使您的测试通过，但允许这样做，除非在下面列出的情况下。

    • 您不得忽略以下验证。在批准之前，必须修复它们并从文件中删除它们。

      • validate-modules:doc-choices-do-not-match-spec

      • validate-modules:doc-default-does-not-match-spec

      • validate-modules:doc-missing-type

      • validate-modules:doc-required-mismatch

      • validate-modules:mutually_exclusive-unknown

      • validate-modules:no-log-needed（在参数规范中使用no_log=False来标记误报！）

      • validate-modules:nonexistent-parameter-documented

      • validate-modules:parameter-list-no-elements

      • validate-modules:parameter-type-not-in-doc

    • 以下验证不得忽略，除非在特定情况下

      • validate-modules:undocumented-parameter：这只能在以下两种情况下忽略

        1. 一个危险的模块参数已被弃用或删除，并且存在代码来告知用户他们不应该再使用此特定参数，或者它已故意停止工作。

        2. 模块参数仅用于从伴随的动作插件传递数据。

    • ignore-*.txt文件中的所有条目都必须在每个条目的文件中添加注释进行说明。例如plugins/modules/docker_container.py use-argspec-type-path # uses colon-separated paths, can't use type=path。

  • 您必须针对集合支持的每个“主要版本”（2.14、2.16、2.17 等）ansible-core运行 CI。（通常是稳定-xxx分支的HEAD。）

  • 所有 CI 测试都必须针对每个拉取请求运行，并且在合并之前应该通过。

  • 至少健全性测试必须针对发布集合的提交运行；如果它们没有通过，则不会发布集合。

    • 如果集合具有集成/单元测试，则也应该运行它们；如果它们没有通过，则应该分析错误以决定它们是否应该阻止发布。

  • 所有 CI 测试都必须定期运行（每晚，或至少每周一次），以确保对没有定期提交的仓库针对每个测试的 ansible-core 版本的最新版本的 ansible-test 进行测试。必须定期检查定期 CI 运行的结果。

所有上述内容都可以通过使用GitHub Action 模板来实现。

要了解如何向您的集合添加测试，请参见

在集合之间移动模块时

有关完整详情，请参见将内容迁移到不同的集合。

通常，我们不反对在集合之间移动内容，也不反对将 Ansible 中包含的集合中的内容移动到 Ansible 包外部的集合，只要不违反语义版本控制即可。更准确地说，如果目标集合是原始集合的依赖项，则用重定向替换内容只是次要更改。（有关向 Ansible 中包含的集合添加新依赖项的更多信息，请参见集合依赖项。）

对于社区“全部捕获”集合，我们有略微不同的规则。我们允许在以下条件下将内容从 community.general 和 community.network 移动到 Ansible 之外的其他集合：

  1. 新集合已获得适当的许可，并遵循贡献者许可协议策略。

  2. 在宣布弃用模块的计划后的四周内，在过去 6 个月中为该内容做出贡献的任何贡献者都没有异议。

  3. 至少有 6 个月的弃用期，在此期间会显示弃用警告。弃用通知必须提到该内容已移动到 Ansible 社区包外部的集合，并且用户需要单独安装该集合。

  4. 如果社区成员或贡献者在6个月内提出充分理由取消迁移，指导委员会将讨论这些理由并进行投票，然后再移除内容。

仅当能够确保完全向后兼容时才添加重定向。如果未使用重定向，则必须使用墓碑式删除，并且墓碑消息需要明确提及新的集合，以及新集合中的内容并非完全向后兼容。

开发规范

您集合中的所有模块

  • 必须满足规范、技巧和陷阱中列出的所有要求。

  • 必须满足幂等性的概念：如果模块使用相同的输入集重复运行，则不会对系统进行任何更改。

  • 不得使用特殊的state选项值（如get、list、query或info）查询信息 - 请改用创建新的_info或_facts模块（更多信息，请参考模块开发指南）。

  • 所有*_info和*_facts模块必须支持check_mode（更多信息，请参考开发规范）。

集合依赖

注释：如果foo.bar依赖于baz.bam，则称baz.bam为被依赖的集合，foo.bar为依赖集合。

  • 集合不得依赖于ansible包中未包含的集合。

  • 集合依赖必须发布在Galaxy上。

  • 集合依赖必须具有最低版本限制，至少为1.0.0。

    • 这意味着所有集合依赖都必须指定最低版本限制，并且这些最低版本限制应该是稳定的版本，而不是0.x.y形式的版本。

    • 创建具有尚在开发中的集合依赖的新集合时，需要注意Galaxy会检查所需版本中是否存在依赖项。

      1. 假设foo.bar依赖于foo.baz。

      2. 首先将foo.baz发布为1.0.0。

      3. 然后修改foo.bar的galaxy.yml，为foo.baz指定'>=1.0.0'。

      4. 最后将foo.bar发布为1.0.0。

  • Ansible中包含的集合之间的依赖关系必须有效。如果依赖关系被破坏，则必须固定相关的集合，以便所有依赖关系再次有效。这意味着保留或仅部分递增上一个版本的版本号，以便生成的版本集没有无效的依赖关系。

  • 如果某个集合长期存在过于严格的依赖关系，并强制其依赖的另一个集合滞后，则该集合将从下一个Ansible主要版本中移除。“较长时间”的含义取决于下一个Ansible主要版本发布的时间。如果依赖集合阻止其依赖的集合的新主要版本包含在下一个Ansible主要版本中，则为了避免阻塞被依赖的集合，依赖集合将从该主要版本中移除。

  • 我们强烈建议集合也针对其依赖项的main分支进行测试，以确保尽早检测与这些依赖项未来版本的兼容性问题，并及时解决这些问题以避免此类问题。依赖于其他集合的集合必须了解，当它们无法确保与其依赖项的最新版本兼容时，它们存在被移除的风险。

  • Ansible中包含的集合不得依赖于其他集合，除非它们满足以下情况之一：

    1. 它们对Ansible中包含的其他集合的一个（或多个）主要版本具有宽松的依赖关系。例如，ansible.netcommon: >=1.0.0，或ansible.netcommon: >=2.0.0, <3.0.0。如果集合依赖于此版本范围之外的新主要版本的版本，并且这些版本将包含在下一个Ansible主要版本中，则依赖集合将从下一个Ansible主要版本中移除。此截止日期为功能冻结日期。

    2. 指导委员会明确允许这样做。

示例

  1. community.foo 1.2.0依赖于community.bar >= 1.0.0, < 1.3.0。

    • 现在community.bar创建了一个新版本1.3.0。当community.foo没有创建具有宽松依赖关系的新版本时，我们必须在下一个Ansible版本中包含community.bar 1.2.x，即使1.3.0可用。

    • 如果community.foo一段时间内没有放松对community.bar的依赖，则community.foo将从下一个Ansible主要版本中移除。

    • 不幸的是，community.bar必须保持在1.2.x，直到community.foo被移除（在下一个主要版本中），或者放松其要求，以便可以包含更新的community.bar 1.3.z版本。

  2. community.foonetwork依赖于ansible.netcommon >= 2.0.0, <3.0.0。

    • 在这个Ansible主要版本周期中发布了ansible.netcommon 4.0.0。

    • community.foonetwork必须在下一个Ansible主要版本的特性冻结之前发布一个新版本，允许依赖所有ansible.netcommon 4.x.y版本，否则它将从下一个Ansible主要版本中移除。

其他要求

  • 在内容从其他当前包含的集合（例如community.general或community.network）中移出之后，或者新的集合满足所有要求后，请参阅在ansible-build-data存储库的README中添加新的集合。

  • 指导委员会可以拒绝集合包含请求或将集合从Ansible包中排除，即使该集合满足本文档中列出的要求。详情请参阅集合包含请求工作流程。

另请参见

Ansible集合创建者路径

Ansible集合创建者旅程的一致概述