Ansible 集合开发周期

Ansible 开发人员（包括社区贡献者）在许多不同的存储库中添加新功能、修复错误并更新代码。这些存储库包含使 Ansible 能够执行特定任务的插件和模块，例如将用户添加到特定数据库或配置特定网络设备。这些存储库包含集合的源代码。

对集合的开发在宏观和微观层面上进行。每个集合都有自己的宏观开发周期。有关集合开发周期的更多信息，请参见 为 Ansible 维护的集合做贡献。PR 的微观层级生命周期在集合和 ansible-core 中类似。

宏观开发：路线图、版本和项目

如果您想关注有关将在即将发布的 Ansible 包中添加哪些功能以及正在修复哪些错误的对话，您可以关注这些资源

• the 路线图

• the Ansible 版本计划

• the Ansible 社区工作组 .

微观开发：PR 的生命周期

如果您想为集合贡献功能或修复错误，您必须打开一个**拉取请求**（简称“PR”）。GitHub 提供了对 拉取请求流程如何工作 的概述。任何拉取请求的最终目标都是被合并并成为集合的一部分。每个集合都有自己的贡献者指南，因此请在那里查看具体细节。

以下是 PR 生命周期的概述

• 贡献者打开一个 PR

• CI 运行测试套件

• 开发人员、维护者和社区审核 PR

• 贡献者解决审阅者提出的任何反馈

• 开发人员、维护者和社区重新审阅

• PR 合并或关闭

使您的 PR 合并值得

我们不会合并每个 PR。有关使您的 PR 有用、有吸引力和值得合并的提示，请参见 创建第一个集合拉取请求。

创建变更日志片段

大多数变更日志应该强调更改对功能或集合的最终用户的影响，除非更改直接影响开发人员。考虑用户需要了解此更改的哪些内容，并编写变更日志以传达该细节。

变更日志帮助用户和开发人员跟上 Ansible 集合的更改。许多集合从片段构建每个版本的变更日志。对于使用此模型的集合，您**必须**在更改功能或修复错误的任何 PR 中添加变更日志片段。

您不需要为以下 PR 添加变更日志片段

• 添加新的模块和插件，因为 Ansible 工具会自动执行此操作；

• 仅包含文档更改。

注意

一些集合要求每个拉取请求都包含一个变更日志片段。它们使用 trivial: 部分来记录上面提到的在构建版本变更日志时将被跳过的条目。

更准确地说

• 每个错误修复 PR 都必须包含一个变更日志片段。唯一的例外是对尚未包含在版本中的更改的修复。

• 每个功能 PR 都必须包含一个变更日志片段。

• 新的模块和插件（包括 jinja2 过滤器和测试插件）必须在文档中正确设置 version_added 条目，并且不需要变更日志片段。工具通过其 version_added 值检测新的模块和插件，并在下一个版本的变更日志中自动宣布它们。

我们为小版本以及主要版本构建简短的摘要变更日志。如果您回溯错误修复，请在回溯 PR 中包含一个变更日志片段。

创建变更日志片段

一个基本的变更日志片段是一个 .yaml 或 .yml 文件，放置在 changelogs/fragments/ 目录中。每个文件都包含一个 yaml 字典，其中包含 bugfixes 或 major_changes 等键，后面跟着一个错误修复或功能的变更日志条目列表。每个变更日志条目都是嵌入在 yaml 文件中的 rst，这意味着某些结构需要转义，以便它们可以被 rst 解释而不是 yaml 解释（或者如果您愿意，可以为 yaml 和 rst 都转义）。每个 PR **必须**使用一个新的片段文件，而不是添加到现有的文件中，这样我们就可以将更改追溯到引入它的 PR。

添加新的模块或插件的 PR 不一定需要变更日志片段。请参见 创建变更日志片段。另请参见 变更日志片段条目格式，了解变更日志片段应具有的精确格式。

要创建变更日志条目，请在相应存储库的 changelogs/fragments/ 目录中创建一个具有唯一名称的新文件。文件名应包含 PR 编号和更改的描述。它必须以文件扩展名 .yaml 或 .yml 结尾。例如： 40696-user-backup-shadow-file.yaml

单个变更日志片段可能包含多个部分，但大多数只会包含一个部分。顶层键（bugfixes、major_changes 等）在 配置文件 中定义，用于我们的 版本说明工具。以下是有效的部分以及每个部分的描述

breaking_changes

**必须**包含会破坏现有剧本或角色的更改。这包括对现有行为的任何更改，这些更改迫使用户更新任务。破坏性更改意味着用户在更新时**必须**进行更改。破坏性更改**必须**仅发生在集合的主要版本中。用现在时写，并清楚地描述最终用户现在必须遵循的新行为。显示在变更日志和 移植指南 中。

breaking_changes:
  - ec2_instance - instance wait for state behavior no longer waits for the instance monitoring status to become OK when launching a new instance. If plays require the old behavior, the action will need to specify ``state: started`` (https://github.com/ansible-collections/amazon.aws/pull/481).

major_changes

对 ansible-core 或集合进行重大更改。不应包括单个模块或插件的更改。必须包括影响集合大部分或全部的非破坏性更改（例如，更新以支持整个集合的新 SDK 版本）。重大更改意味着用户可以选择在更新时进行更改，但并非必须。可用于宣布未来版本中的重要即将发布的 EOL 或破坏性更改。（理想情况下，在已知的情况下提前 6 个月。参见 此示例）。使用现在时态描述新增内容。可选择包含一句“先前…”语句来帮助用户识别旧行为应该在哪里发生更改。显示在变更日志和 移植指南 中。

major_changes:
  - bitbucket_* modules - client_id is no longer marked as ``no_log=true``. If you relied on its value not showing up in logs and output, mark the whole task with ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/2045).

minor_changes

对 ansible-core、模块或插件进行的次要更改。包括在模块中添加新参数，或对现有参数进行非破坏性行为更改，例如在 choices[] 中添加新值。次要更改是增强功能，而不是错误修复。使用现在时态。

minor_changes:
  - nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6 routes (https://github.com/ansible-collections/community.general/issues/4059).

deprecated_features

已弃用的功能，计划在未来版本中删除。使用过去时态。在可能的情况下，包含已弃用功能的替代方案。显示在变更日志和 移植指南 中。

deprecated_features:
  - mail callback plugin - not specifying ``sender`` is deprecated and will be disallowed in ``community.general`` 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140).

removed_features

先前已弃用，现已删除的功能。使用过去时态。在可能的情况下，包含已弃用功能的替代方案。显示在变更日志和 移植指南 中。

removed_features:
  - acme_account_facts - the deprecated redirect has been removed. Use ``community.crypto.acme_account_info`` instead (https://github.com/ansible-collections/community.crypto/pull/290).

security_fixes

解决 CVE 或安全问题的修复。必须对所有 CVE 使用 security_fixes。使用现在时态。包含指向 CVE 信息的链接。

security_fixes:
  - win_psexec - ensure password is masked in ``psexec_``command return result (https://github.com/ansible-collections/community.windows/issues/43).

bugfixes

解决问题的修复。不应用于次要增强功能（请改用 minor_change）。使用过去时态描述问题，使用现在时态描述修复。

bugfixes:
  - apt_repository - fix crash caused by a timeout. The ``cache.update()`` was raising an ``IOError`` because of a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995).

known_issues

当前未修复或不会修复的已知问题。使用现在时态描述问题，使用祈使句描述任何可用的解决方法。

known_issues:
  - idrac_user - module may error out with the message ``unable to perform the import or export operation`` because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.(https://github.com/dell/dellemc-openmanage-ansible-modules/pull/303).

trivial

不需要正式发布变更日志条目的更改。trivial 变更日志片段不包含在发布的变更日志输出中，可用于诸如维护、文档和仅测试更改之类的更改。对于需要针对每个拉取请求进行变更日志片段的集合，可以使用 trivial。

trivial:
  - aws_ec2 - fix broken integration test (https://github.com/ansible-collections/amazon.aws/pull/1269).

每个变更日志条目都必须在末尾包含一个指向其问题的链接（在括号中）。如果没有相应的 issue，该条目必须包含指向 PR 本身的链接。

大多数变更日志条目是 bugfixes 或 minor_changes。

变更日志片段条目格式

编写变更日志条目时，请使用以下格式

- scope - description starting with a lowercase letter and ending with a period at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or if there is no issue, reference to a pull request itself).

范围通常是模块或插件名称，或者是一组模块或插件，例如，lookup plugins。虽然模块名称可以（应该）直接提及 (foo_module)，但插件名称后面始终应跟类型 (foo inventory plugin)。

对于实际上没有范围的更改（例如，影响整个集合的更改），请使用以下格式

- Description starting with an uppercase letter and ending with a dot at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself).

以下是一些示例

bugfixes:
  - apt_repository - fix crash caused by ``cache.update()`` raising an ``IOError``
    due to a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995).

minor_changes:
  - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443).

bugfixes:
  - copy - the module was attempting to change the mode of files for
    remote_src=True even if mode was not set as a parameter.  This failed on
    filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444).

您可以在 community.general 开发分支的变更日志目录 中找到更多示例变更日志片段。

编写完 PR 的变更日志片段后，提交该文件并将其包含在拉取请求中。

新 jinja2 插件、角色和剧本的变更日志片段条目格式

虽然在生成的变更日志中会自动提及不是 jinja2 过滤器或测试插件的新模块和插件，但不会提及 jinja2 过滤器和测试插件、角色和剧本。为了确保提及它们，需要使用特定格式的变更日志片段

# A new jinja2 filter plugin:
add plugin.filter:
  - # The following needs to be the name of the filter itself, not of the file
    # the filter is included in!
    name: to_time_unit
    # The description should be in the same format as short_description for
    # other plugins and modules: it should start with an upper-case letter and
    # not have a period at the end.
    description: Converts a time expression to a given unit

# A new jinja2 test plugin:
add plugin.test:
  - # The following needs to be the name of the test itself, not of the file
    # the test is included in!
    name: asn1time
    # The description should be in the same format as short_description for
    # other plugins and modules: it should start with an upper-case letter and
    # not have a period at the end.
    description: Check whether the given string is an ASN.1 time

# A new role:
add object.role:
  - # This should be the short (non-FQCN) name of the role.
    name: nginx
    # The description should be in the same format as short_description for
    # plugins and modules: it should start with an upper-case letter and
    # not have a period at the end.
    description: A nginx installation role

# A new playbook:
add object.playbook:
  - # This should be the short (non-FQCN) name of the playbook.
    name: wipe_server
    # The description should be in the same format as short_description for
    # plugins and modules: it should start with an upper-case letter and
    # not have a period at the end.
    description: Wipes a server