Ansible 集合创建者路径

注意

如果您不熟悉 Ansible 集合（collections），请先阅读 使用 Ansible 集合指南。

Ansible 集合是 Ansible 内容的一种分发格式，可以包含 playbook、角色（roles）、模块（modules）和插件（plugins）。一个典型的集合旨在解决一组相关的用例。例如，community.dns 集合包含了用于处理 DNS 的模块和插件。

您可以安装他人制作的集合，或通过 Ansible Galaxy 等分发服务器与社区分享您的集合。经过认证的集合可以发布到 Red Hat Automation Hub（Red Hat Ansible Automation Platform 的一部分）。

创建并分享集合是为 Ansible 项目做出贡献的绝佳方式。

Ansible 社区软件包由 ansible-core 组成，除了其他核心组件外，它还包括由核心团队维护的 ansible.builtin 集合，以及一套由社区维护的集合。

本指南的目的是为您（潜在的）内容创建者提供一个一致的 Ansible 集合创建流程概览：从第一个模块/角色的构思开始，直到您的集合被包含在 Ansible 社区软件包中。集合开发指南章节提供了该流程中更详细方面的参考。整个流程包含以下里程碑：

考察现有可用方案

如果您对新的角色或模块/插件有想法，但已经有足够的方案能够解决您的自动化问题，则无需重复造轮子。

因此，请首先考察目前可用的内容，包括：

如果发现的方案不够完善或存在缺陷，请考虑对其进行改进而非创建自己的方案。每个集合都包含关于在哪里提交问题（issue）以提出增强建议的信息。

如果您已经编写了内容并在工作流中使用，仍可以考虑将其整合到现有方案中。然而，如果这些选项不适用于您的集合构思，我们鼓励您创建并分享自己的作品。

创建您的内容

您已经尝试寻找但未发现能解决您自动化问题的合适方案。

请参考以下指南之一：

将内容放入集合中

您已经创建了新内容。

现在是时候创建一个可重用且可分享的集合了。请参阅 开发集合指南 学习如何操作。

我们建议您使用 collection_template 仓库 作为集合的基础。

编写优秀的集合用户文档

您的集合 README.md 文件应包含快速安装和使用指南。您可以参考 community.general 集合的 README 文件 作为示例。

如果您的集合包含模块或插件，请确保其文档详尽。请参阅 模块格式与文档指南 和 Ansible 文档风格指南 以了解更多信息。

发布您的集合源代码

将您的集合发布在软件开发和版本控制平台（如 GitHub）上。

可以是您的个人仓库或组织仓库。您也可以申请在 ansible-collections 组织下创建仓库。

请确保您的集合包含详尽的许可（license）信息。Ansible 是一个开源项目，因此我们鼓励您使用开源许可。如果您计划提交集合以纳入 Ansible 社区软件包，您的集合必须满足许可要求。

如果您使用了我们之前建议的 collection_template 仓库 作为骨架，其中已经包含了 GNU GPL v3 许可。

遵循版本控制规范

在发布集合新版本时，请考虑以下推荐实践：

理解并实施测试与 CI

本节适用于包含模块和插件的集合。

关于角色测试，请参阅 Ansible Molecule 项目。

添加测试

测试您的集合可确保代码运行良好，并能与 ansible-core 等其他组件集成。

请参考以下文档：

实施持续集成

现在，请确保当集合仓库中创建 pull request 时，能够使用 GitHub Actions 或 Azure Pipelines 等 CI 工具自动进行测试。

collection_template 仓库 包含 GitHub Actions 模板，您可以对其进行调整并用于启用您仓库中的工作流。

提供优秀的贡献者与维护者文档

请参考 collection_template/README.md 作为示例。

在分发服务器上发布您的集合

为了分发您的集合并方便他人使用，请将集合发布在一个或多个分发服务器上。请参阅 分发集合指南 学习如何操作。

使您的集合成为 Ansible 社区软件包的一部分

使您的集合满足 Ansible 社区软件包集合要求 并提交申请以将其纳入。请参阅 纳入流程描述 了解具体操作。

维护

维护您的集合。详情请参阅 Ansible 集合维护者指南。

沟通

参与社区互动。请参阅 Ansible 沟通指南 以了解可用的沟通选项。

另请参阅

开发集合

一组关于集合（collection）开发方面的指南