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 中包含变更日志片段。

创建变更日志片段

基本的变更日志片段是一个.yaml或.yml文件，放置在changelogs/fragments/目录中。每个文件都包含一个 yaml 字典，其中包含诸如bugfixes或major_changes之类的键，后跟错误修复或功能的变更日志条目列表。每个变更日志条目都以 rst 嵌入在 yaml 文件中，这意味着某些构造需要转义，以便它们可以被 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).

每个变更日志条目都必须在末尾的括号内包含指向其问题的链接。 如果没有相应的问题，则该条目必须包含指向 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 开发分支的changelog 目录中找到更多示例变更日志片段。

在为您的 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