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-core 或集合的重大更改。 不应包含单个模块或插件的更改。 必须包含影响集合大部分或全部的非破坏性更改（例如，更新以支持整个集合的新 SDK 版本）。 重大更改意味着用户可以选择在更新时进行更改，但并非必须。 可以用来宣布未来版本中即将发生的重要的 EOL 或破坏性更改。 （理想情况下，如果已知，则提前 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).
minor_changes

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

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

已弃用的功能，计划在未来版本中删除。 使用过去时态，并提供可用的替代方案，以代替正在弃用的内容。 在变更日志和 移植指南 中显示。

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

以前已弃用且现已删除的功能。 使用过去时态，并提供可用的替代方案，以代替正在弃用的内容。 在变更日志和 移植指南 中显示。

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

解决 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).
bugfixes

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

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

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.17 版本的变更日志目录 中找到更多示例变更日志片段。

编写完 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.17 是回滚的目标发布分支

  • 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.17/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.17

  1. 将相关 commit SHA 从 devel 分支 cherry-pick 到你的 feature 分支，根据需要处理合并冲突

git cherry-pick -x [SHA_FROM_DEVEL]

  1. 为更改添加一个 变更日志片段，并提交它。

  2. 将你的 feature 分支推送到你在 GitHub 上的 fork

git push origin backport/2.17/[PR_NUMBER_FROM_DEVEL]

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

  2. 发布经理将在下一个次要版本发布之前决定是否合并回滚 PR。 不需要跟进。 只要确保自动测试（CI）是绿色的即可。

注意

分支名称 backport/2.17/[PR_NUMBER_FROM_DEVEL] 有些随意，但传达了有关分支目的的意义。 此分支名称格式不是必需的，但它可能会有所帮助，尤其是在针对多个稳定分支进行多个回滚 PR 时。

注意

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