创建您的第一个集合拉取请求

本节描述创建第一个补丁并向集合提交拉取请求所需的所有步骤。

准备您的环境

注意

这些步骤假设使用安装了 git 的 Linux 工作环境。

  1. 安装并启动 docker 或 podman。这确保测试在与 CI 中相同的环境中正确隔离并运行。

  2. 安装 Ansible 或 ansible-core。您需要 ansible-test 实用程序，该实用程序由这两个软件包中的任何一个提供。

  3. 在您的主目录中创建以下目录

$ mkdir -p ~/ansible_collections/NAMESPACE/COLLECTION_NAME

例如，如果集合是 community.mysql，它将是

$ mkdir -p ~/ansible_collections/community/mysql

  1. 通过 GitHub Web 界面分叉集合存储库。

  2. 从您的个人资料将分叉的存储库克隆到创建的路径

$ git clone https://github.com/YOURACC/COLLECTION_REPO.git ~/ansible_collections/NAMESPACE/COLLECTION_NAME

如果您更喜欢使用 SSH 协议

$ git clone [email protected]:YOURACC/COLLECTION_REPO.git ~/ansible_collections/NAMESPACE/COLLECTION_NAME

  1. 转到您新克隆的存储库。

$ cd ~/ansible_collections/NAMESPACE/COLLECTION_NAME

  1. 确保您位于默认分支（通常为 main）

$ git status

  1. 显示远程。应该只有 origin 存储库

$ git remote -v

  1. 添加 upstream 存储库

$ git remote add upstream https://github.com/ansible-collections/COLLECTION_REPO.git

这是您从哪个存储库分叉的。

  1. 更新您的本地默认分支。假设它是 main

$ git fetch upstream
$ git rebase upstream/main

  1. 为您的更改创建一个分支

$ git checkout -b name_of_my_branch

更改代码

注意

不要在一个拉取请求中混合多个不紧密相关的错误修复或功能。对不同的更改使用单独的拉取请求。

您应该首先编写集成测试和单元测试（如果适用）。这些可以验证错误是否存在（在您修复代码之前）并验证您的代码修复了该错误，一旦测试通过。

注意

如果您在编写或运行测试方面遇到任何困难，或者不确定是否可以覆盖这种情况，您可以跳过此步骤。其他贡献者可以在需要时帮助您进行测试。

注意

一些集合没有集成测试。在这种情况下，需要进行单元测试。

所有集成测试都存储在 tests/integration/targets 子目录中。转到包含您要更改的模块名称的子目录。例如，如果您正在修复 community.mysql 集合中的 mysql_user 模块，它的测试位于 tests/integration/targets/test_mysql_user/tasks。

该 main.yml 文件包含测试任务并包含其他测试文件。寻找合适的测试文件来集成您的测试，或创建并包含一个专用的测试文件。您可以使用现有测试文件之一作为草稿。

修复错误时，编写一个从问题中重现错误的任务。

将报告的案例放入测试中，然后使用以下命令运行集成测试

$ ansible-test integration name_of_test_subdirectory --docker -v

例如，如果您更改的测试文件存储在 tests/integration/targets/test_mysql_user/ 中，则命令如下

$ ansible-test integration test_mysql_user --docker -v

如果您需要更详细的输出，可以使用 -vv 或 -vvv 参数。

在上面的示例中，默认测试映像会自动下载并用于创建和运行测试容器。对于平台无关的集成测试（例如云模块测试），请使用默认测试映像。

如果您需要针对特定发行版运行测试，请参阅 支持的容器映像列表。例如

$ ansible-test integration name_of_test_subdirectory --docker fedora35 -v

注意

如果您不确定是否应该使用默认映像进行测试或使用特定映像，请跳过整个步骤 - 社区可以稍后帮助您。您也可以尝试使用集合存储库的 CI 来确定使用了哪些容器。

如果测试成功运行，通常有两种可能的结果

  • 如果错误没有出现并且测试已成功通过，请要求报告者提供更多详细信息。它可能不是错误，或者可能与使用的特定软件版本或报告者本地环境配置的具体情况有关。

  • 错误已出现并且测试已失败，如预期的那样，显示了报告的症状。

修复错误

有关 Ansible 模块开发的一些一般指南，请参阅 将您的模块贡献到现有的 Ansible 集合，这些指南可能有助于您为错误创建一个良好的代码修复。

测试您的更改

  1. 安装 flake8 (pip install flake8，或在您的操作系统上安装相应的软件包)。

  2. 对更改的文件运行 flake8

$ flake8 path/to/changed_file.py

这将显示未使用的导入，这些导入不会显示在健全性测试中，以及其他常见问题。或者，您可以使用 --max-line-length=160 命令行参数。

  1. 运行健全性测试

$ ansible-test sanity path/to/changed_file.py --docker -v

如果它们失败，请仔细查看输出 - 它很有用，可以帮助您快速识别问题行。健全性错误通常与不正确的代码和文档格式有关。

  1. 运行集成测试

$ ansible-test integration name_of_test_subdirectory --docker -v

例如，如果您更改的测试文件存储在 tests/integration/targets/test_mysql_user/ 中，则命令为

$ ansible-test integration test_mysql_user --docker -v

如果您需要更详细的输出，可以使用 -vv 或 -vvv 参数。

有两种可能的结果

  • 它们失败了。查看命令的输出。修复代码中的问题并再次运行。重复此循环，直到测试通过。

  • 它们通过了。请记住它们最初是失败的吗？祝贺你！您已修复了错误。

除了集成测试之外，您还可以使用单元测试来涵盖您的更改。当集成测试不适用于集合时，这通常是必需的。

我们使用 pytest 作为测试框架。

包含单元测试的文件存储在 tests/unit/plugins/ 目录中。如果您想运行单元测试，例如，对于 tests/unit/plugins/test_myclass.py，则命令为

$ ansible-test units tests/unit/plugins/test_myclass.py --docker

如果您想运行集合中所有可用的单元测试，请运行

$ ansible-test units --docker

提交拉取请求

  1. 使用信息丰富但简短的提交消息提交您的更改

$ git add /path/to/changed/file
$ git commit -m "module_name_you_fixed: fix crash when ..."

  1. 将分支推送到 origin（您的分叉）

$ git push origin name_of_my_branch

  1. 在浏览器中，导航到 upstream 存储库 (http://github.com/ansible-collections/COLLECTION_REPO).

  2. 单击 拉取请求 选项卡。

GitHub 正在跟踪您的分叉，因此它应该看到其中的新分支并自动提供创建拉取请求。有时 GitHub 不会这样做，您应该自己单击 新建拉取请求 按钮。然后在 比较更改 标题下选择 跨分叉比较。

  1. 在右侧下拉列表中选择您的存储库和您推送到其中的新分支。确认。

  1. 使用您要提到的所有信息填写拉取请求模板。

  2. 在拉取请求的描述中放入 Fixes + link to the issue。

  3. 在拉取请求的标题中放入 [WIP] + short description。在描述开头提及您要修改的模块/插件的名称。

  4. 单击 创建拉取请求。

  1. 将 更改日志片段 添加到 changelogs/fragments 目录。它将在发行说明中发布，因此用户会知道有关修复的信息。

  1. 运行代码片段的健全性测试。

$ ansible-test sanity changelogs/fragments/ --docker -v

  1. 如果测试通过，提交并推送更改。

$ git add changelogs/fragments/myfragment.yml
$ git commit -m "Add changelog fragment"
$ git push origin name_of_my_branch

  1. 验证每次提交后在 Red Hat 基础设施上自动运行的 CI 测试是否成功。

您将在拉取请求底部看到 CI 状态。如果它们是绿色的，并且您认为在有人仔细查看之前您不想添加更多提交，请从标题中删除 [WIP]。在评论中提及问题报告者，并让贡献者知道拉取请求“已准备好审查”。

  1. 等待审查。您也可以在 #ansible-community Matrix/Libera.Chat IRC 频道 中请求审查。

  2. 如果社区认为拉取请求看起来不错，提交者将合并它。

有关此过程的更详细内容，请参阅 Ansible 开发者指南.