ansible-build-data¶

保存构建 ansible 社区软件包时生成的持久化结果。这些信息可能会被其他项目和脚本引用。

问题追踪器¶

本仓库的问题追踪器处理 ansible 构建的各个方面，包括：

追踪发布日期，
追踪版本的阻碍项 (Blockers)，
追踪集合的添加、重命名和删除，
追踪与构建过程相关的发布问题
这包括导致软件包无法安装，或无法从 PyPI 版本构建系统软件包的问题；
追踪并讨论 ansible 社区软件包的其他问题
这包括包含的集合中存在的重要问题，且集合维护者未采取行动，例如与当前 ansible-core 版本的大规模不兼容、违反语义化版本控制，以及普遍违反 Ansible 纳入要求的情况；
这包括集合中具有广泛影响的主要漏洞或安全漏洞，且未被集合维护者解决，或由于某种原因无法在集合级别解决。

本问题追踪器不用于追踪 ansible-core 或 ansible 软件包中包含的集合的常规 bug 或功能请求，也不用于用户支持。此类问题将被关闭。 请转而查看 ansible-core 问题追踪器、相关集合的问题追踪器，或考虑在 Ansible 论坛寻求帮助。

里程碑¶

发布工程师会在发布软件包之前的一段时间检查里程碑，以确保有足够时间解决所有相关问题。

阻碍项 (Blockers)¶

在 Ansible 社区软件包发布工作流的语境下，发布阻碍项 (release blocker) 是指不允许发布软件包的情况。它可能伴随新的 ansible-core 版本发布而出现并影响许多包含的集合，或者以任何其他方式严重影响 ansible 软件包的一致性工作。影响的严重程度由指导委员会 (Steering Committee) 在具体案例中决定。发布阻碍项必须在发布继续进行之前得到解决。

如果出现潜在的发布阻碍项，需要执行以下操作：

创建一个社区议题 (community topic) 来描述潜在的阻碍项。
如果指导委员会认为该情况属于发布阻碍项，请在本仓库中创建一个 issue。
在 issue 上打上 blocker 标签。
将该 issue 添加到受影响发布版本的里程碑中。

数据结构¶

::

ansible-build-data
└── 3
    ├── ansible-3.0.0.deps
    ├── ansible-3.1.0.deps
    ├── ansible-3.build
    └── ansible.in

Ansible 的每个主版本在仓库中都有一个以 Ansible X.Y 版本号命名的子目录（例如：3）。
在每个版本目录中，有一个 ansible.in 文件，列出了该版本 Ansible 中包含的集合。文件每行包含一个 namespace.collection。该文件由负责构建该版本 Ansible 的人员创建。
此外还会有一个 ansible-X.build 文件。该文件包含由 namespace.collection 及其后跟版本范围组成的行，例如：

awx.awx: >=11.0.0,<12.0.0

版本范围指定了与初始 Ansible-X.Y.0 版本冻结时可用版本向后兼容的潜在集合版本。只有在此范围内的集合版本才会被考虑用于 Ansible 的次要版本更新。该文件由 antsibull-build new-ansible 命令创建。

最后，会有多个 ansible-X.Y.Z.deps 文件。这些文件包含由 namespace.collection 及其后跟单个版本组成的行，例如：

awx.awx: 11.2.5

该版本指定了出现在该 Ansible 发布版本中的集合的准确版本。该文件由 antsibull-build single 命令创建。

代码检查 (Linting)¶

要对本仓库中的文件进行 lint 检查，请运行 nox -e lint。这假设您已安装 nox。

添加新集合¶

下一个 Ansible 主版本¶

要将集合添加到尚未达到功能冻结 (feature freeze) 的下一个 Ansible 主版本中：

将集合添加到以相应数字命名的子目录中的 ansible.in 文件中。
在同一个子目录中，将集合添加到 collection-meta.yaml 文件中，如下所示：
maintainers (列表): 集合维护者的 Github 用户名。
repository (字符串): 集合 git 仓库的 URL。
collection-directory (字符串): 集合相对于 Git 仓库根目录的顶层目录。顶层目录是 galaxy.yml 所在的位置。对于大多数集合，应设置为 .。但某些集合（如 awx.awx）将集合存储在子目录中。在这种情况下，collection-directory 应设置为 ./SUBDIRECTORY（SUBDIRECTORY 是实际目录的占位符）。
changelog-url (字符串): 如果集合未在 changelogs/changelog.yaml 中提供变更日志，则需要添加实际变更日志的 URL。否则，应省略此字段。

collections:
  # NAMESPACE.NAME
  community.example:
    # The Github usernames of this collection's maintainers
    maintainers:
      - person1
      - person2
    # The URL to the collection's SCM repository.
    repository: https://github.com/ansible-collections/community.example
    # This is the directory where galaxy.yml is stored relative to the
    # repository root.
    #
    # For collections stored in the repository root:
    collection-directory: "."
    # For collections stored in a subdirectory:
    collection-directory: "./SUBDIRECTORY"
    # This is an optional field that should only be populated if the collection
    # doesn't include a changelogs/changelog.yaml file.
    # changelog-url: ...

当前 Ansible 主版本¶

要将集合添加到当前 Ansible 主版本的下一个次要版本中：

将集合添加到以相应数字命名的子目录中的 ansible.in 文件中。
在同一个子目录中，将集合及其版本范围添加到 ansible-X.build 文件中。
在同一个子目录中，将集合添加到 collection-meta.yaml 文件中。
需要在此列出维护者的 GitHub 用户名。
如果集合未在 changelogs/changelog.yaml 中提供变更日志，则需要添加实际变更日志的 URL。

重命名集合¶

在某些情况下，Ansible 中包含的某个集合被重命名，但其内容基本保持不变（除了重命名、调整文档以及其他可能的微小更改）。在这种情况下，如果遵循以下步骤，可以将新集合纳入并移除旧集合。

为简单起见，假设下一个 Ansible 次要版本是 X.Y.0，且最新版本为 a.b.c 的集合 foo.bar 已重命名为最新版本为 A.B.C 的 baz.bam。

baz.bam A.B.C 必须与 foo.bar a.b.c 兼容（除了插件重命名）。任何选项的重命名必须提供向后兼容的别名，且不能更改默认值或语义。
baz.bam A.B.C 可以被添加到 Ansible X.Y.0 中。
在 Ansible X.Y.0 的变更日志 (deprecated_features) 中添加一条弃用警告，说明 foo.bar 已重命名为 baz.bam，Ansible (X+1).0.0 将开始提供从 foo.bar 到 baz.bam 的弃用重定向，并且 foo.bar 将在随后的 Ansible 主版本中被移除。
发布一个新版本 foo.bar (a+1).0.0，该版本不再包含实际内容，仅包含指向 baz.bam 的弃用重定向。理想情况下，它应依赖于 baz.bam，以便安装 foo.bar 的用户能够正常使用弃用重定向。
Ansible (X+1).0.0 同时包含 foo.bar (a+1).0.0 以及 baz.bam A.B'.C' 版本或更晚的且仍与步骤 1 中指定的 foo.bar a.b.c 兼容的主版本。
foo.bar 将从 Ansible (X+2).0.0 中移除（需要在其变更日志中作为 removed_features 公告）。