Ansible 开发周期

Ansible 开发者（包括社区贡献者）在许多不同的代码库中添加新功能、修复错误和更新代码。 ansible/ansible 代码库 包含基本功能和函数的代码，例如将模块代码复制到被管理的节点。此代码也称为 ansible-core。其他代码库包含插件和模块，使 Ansible 能够执行特定任务，例如向特定数据库添加用户或配置特定网络设备。这些代码库包含集合的源代码。

对 ansible-core 的开发发生在两个级别。在宏观级别，ansible-core 开发者和维护者使用路线图和项目来规划版本发布和跟踪进度。在微观级别，每个 PR 都有其自身的生命周期。

对集合的开发也发生在宏观和微观级别。每个集合都有其自身的宏观开发周期。有关集合开发周期的更多信息，请参见 为 Ansible 维护的集合作贡献。PR 的微观级别生命周期在集合和 ansible-core 中类似。

宏观开发：ansible-core路线图、版本发布和项目

如果您想了解即将发布的 ansible-core 中将添加哪些功能以及正在修复哪些错误，您可以关注以下资源：

微观开发：PR 的生命周期

如果您想为 ansible-core 或集合贡献功能或修复错误，您必须打开一个**拉取请求**（简称“PR”）。GitHub 提供了关于 拉取请求流程如何工作 的总体概述。任何拉取请求的最终目标都是合并并成为集合或 ansible-core 的一部分。以下是 PR 生命周期概述：

  • 贡献者打开一个 PR（始终针对 devel 分支）

  • ansible-core 使用 Ansibot 来分类 PR。一些集合代码库使用 Ansibullbot 来分类 PR。对于大多数集合，这是手动完成的或通过其他方式完成的。

  • Azure Pipelines 运行测试套件

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

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

  • 开发者、维护者、社区重新审核

  • PR 合并或关闭

  • PR 回传 到一个或多个 stable-X.Y 分支（可选，仅限错误修复）

使您的 PR 值得合并

我们不会合并每个 PR。以下是一些使您的 PR 有用、吸引人且值得合并的技巧。

创建变更日志片段

变更日志帮助用户和开发者了解 ansible-core 和 Ansible 集合的更改。Ansible 和许多集合从片段构建每个版本的变更日志。对于使用此模型的 ansible-core 和集合，您**必须**为更改功能或修复错误的任何 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:
  - ansible-test - automatic installation of requirements for cloud test plugins no longer occurs. The affected test plugins are ``aws``, ``azure``, ``cs``, ``hcloud``, ``nios``, ``opennebula``, ``openshift`` and ``vcenter``. Collections should instead use one of the supported integration test requirements files, such as the ``tests/integration/requirements.txt`` file (https://github.com/ansible/ansible/pull/75605).
major_changes

Ansible 核心代码或集合的主要变更。**不应**包含单个模块或插件的变更。**必须**包含不会破坏兼容性的变更，这些变更会影响集合的全部或大部分内容（例如，更新以跨集合支持新的 SDK 版本）。主要变更意味着用户在更新时可以选择进行变更，但并非必须。可以用来宣布未来版本中重要的即将淘汰的特性或破坏性变更（理想情况下，如果已知，则提前 6 个月。参见此示例）。使用现在时态进行描述，说明新增内容。可以选择包含“之前……”语句，以帮助用户确定旧行为现在应如何更改。变更内容同时显示在变更日志和迁移指南中。

major_changes:
  - ansible-test - all cloud plugins which use containers can now be used with all POSIX and Windows hosts. Previously the plugins did not work with Windows at all, and support for hosts created with the ``--remote`` option was inconsistent (https://github.com/ansible/ansible/pull/74216).
次要变更

Ansible 核心代码、模块或插件的次要变更。这包括向模块添加新参数，或对现有参数进行不会破坏兼容性的行为更改，例如向 choices[] 添加其他值。次要变更属于增强功能，而非错误修复。使用现在时态。

minor_changes:
  - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443).
已弃用的功能

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

deprecated_features:
  - include action - is deprecated in favor of ``include_tasks``, ``import_tasks`` and ``import_playbook`` (https://github.com/ansible/ansible/pull/71262).
已移除的功能

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

removed_features:
  - _get_item() alias - removed from callback plugin base class which had been deprecated in favor of ``_get_item_label()`` (https://github.com/ansible/ansible/pull/70233).
安全修复

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

security_fixes:
  - set_options -do not include params in exception when a call to ``set_options`` fails. Additionally, block the exception that is returned from being displayed to stdout. (CVE-2021-3620).
错误修复

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

bugfixes:
  - ansible_play_batch - variable included unreachable hosts. Fix now saves unreachable hosts between plays by adding them to the PlayIterator's ``_play._removed_hosts`` (https://github.com/ansible/ansible/issues/66945).
已知问题

当前未修复或不会修复的已知问题。使用现在时态，并在可用情况下，对解决方法使用祈使句。

known_issues:
  - ansible-test - tab completion anywhere other than the end of the command with the new composite options provides incorrect results (https://github.com/kislyuk/argcomplete/issues/351).

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

大多数变更日志条目是bugfixes或minor_changes。变更日志工具还支持trivial，这些条目不会列在实际的变更日志输出中，但会被需要每个 PR 的变更日志片段的集合存储库使用。

变更日志片段条目格式

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

- 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).

您可以在 2.18 版本的变更日志目录中找到更多示例变更日志片段。

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

新剧本的变更日志片段条目格式

虽然生成的变更日志会自动提及新的模块、插件和角色，但不会提及剧本。要确保提及它们，需要使用特定格式的变更日志片段。

# 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

在ansible-core中回退已合并的 PR

所有ansible-core PR 必须首先合并到devel分支。拉取请求被接受并合并到devel分支后，以下说明将帮助您创建拉取请求以将更改回退到之前的稳定分支。

我们**不**回退功能。

注意

这些说明假设：

  • stable-2.18是回退的目标发布分支。

  • https://github.com/ansible/ansible.git被配置为名为upstream的git remote。如果您不使用名为upstream的git remote，请相应调整说明。

  • https://github.com/<yourgithubaccount>/ansible.git被配置为名为origin的git remote。如果您不使用名为origin的git remote，请相应调整说明。

  1. 准备您的 devel、stable 和 feature 分支。

git fetch upstream
git checkout -b backport/2.18/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.18

  1. 将相关提交 SHA 从 devel 分支 cherry-pick 到您的 feature 分支，必要时处理合并冲突。

git cherry-pick -x [SHA_FROM_DEVEL]

  1. 添加对更改的变更日志片段，并提交。

  2. 将您的 feature 分支推送到您在 GitHub 上的分支。

git push origin backport/2.18/[PR_NUMBER_FROM_DEVEL]

  1. 针对stable-2.18分支提交backport/2.18/[PR_NUMBER_FROM_DEVEL]的拉取请求。

  2. 发布管理员将在下一个次要版本发布之前决定是否合并回退 PR。无需后续跟进。只需确保自动化测试 (CI) 通过即可。

注意

分支名称backport/2.18/[PR_NUMBER_FROM_DEVEL]在某种程度上是任意的，但传达了分支目的的信息。此分支名称格式不是必需的，但在进行多个稳定分支的多个回退 PR 时，它可能很有帮助。

注意

如果您愿意，可以使用 CPython 的 cherry-picker 工具（pip install --user 'cherry-picker >= 1.3.2'）将提交从 Ansible 的 devel 回退到稳定分支。请查看cherry-picker 文档，了解有关安装、配置和使用的详细信息。