Ansible 集合开发周期

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

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

宏开发：路线图、发布和项目

如果您想关注关于将添加到 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 中包含一个变更日志片段。

创建变更日志片段

基本变更日志片段是一个放置在 changelogs/fragments/ 目录中的 .yaml 或 .yml 文件。每个文件都包含一个 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