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

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

准备您的环境

注意

这些步骤假设使用安装了 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（你的 fork）

$ git push origin name_of_my_branch

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

  2. 点击 Pull requests 标签。

GitHub 正在跟踪你的 fork，因此它应该看到其中的新分支并自动提供创建拉取请求。有时 GitHub 不会这样做，你应该自己点击 New pull request 按钮。然后在 Compare changes 标题下选择 compare across forks。

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

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

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

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

  4. 点击 Create pull request.

  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 开发人员指南.