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

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

准备您的环境

注意

这些步骤假设使用安装了 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 界面 Fork 集合存储库。

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

$ 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

这是您从中 Fork 的存储库。

  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（您的 Fork）

$ git push origin name_of_my_branch

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

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

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

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

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

  2. 在拉取请求的描述中放入 Fixes + 指向问题的链接。

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

  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. 验证在每次提交后在红帽基础架构上自动运行的 CI 测试是否成功。

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

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

  2. 如果社区认为拉取请求没有问题，提交者将会合并它。

有关此过程的更深入细节，请参阅 Ansible 开发者指南。