Ansible 集合开发周期

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

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

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

如果您想关注有关将在即将发布的 Ansible 包中添加哪些功能以及修复哪些 bug 的讨论，您可以关注以下资源：

微观开发：PR 的生命周期

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

以下是 PR 生命周期概述：

  • 贡献者打开一个 PR

  • CI 运行测试套件

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

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

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

  • PR 合并或关闭

使您的 PR 值得合并

我们不会合并每个 PR。请参阅 创建您的第一个集合拉取请求，了解使您的 PR 有用、吸引人且值得合并的技巧。

创建变更日志片段

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

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

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

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

  • 仅包含文档更改。

注意

一些集合要求每个拉取请求都包含一个变更日志片段。他们使用 trivial: 部分来列出上述在构建发布变更日志时将跳过的条目。

更准确地说：

  • 每个 bug 修复 PR 都必须有一个变更日志片段。唯一的例外是修复尚未包含在发布中的更改。

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

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

我们为次要版本和主要版本都构建简短的摘要变更日志。如果您回传 bug 修复，请在回传 PR 中包含变更日志片段。

创建变更日志片段

一个基本的变更日志片段是一个放置在 changelogs/fragments/ 目录中的 .yaml 或 .yml 文件。每个文件都包含一个 yaml 字典，其键如 bugfixes 或 major_changes，后跟 bug 修复或功能的变更日志条目的列表。每个变更日志条目都是嵌入在 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

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

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).
次要变更

对 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:
  - 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:
  - 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).
安全修复

解决 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).
错误修复

解决问题的修复。不应将其用于次要增强功能（请改用 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:
  - 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:
  - 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 开发分支的 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