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

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

准备您的环境

注意

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

  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 + 问题链接。

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

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

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

  2. 如果社区认为拉取请求良好，提交者将合并它。

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