使用发布分支发布集合

集合必须遵循 语义版本控制 规则。有关高级详细信息，请参见 发布集合。

发布计划和公告

  1. 在集合的相应置顶发布问题/社区公告板和 #ansible-community Matrix/IRC 频道 中宣布您发布集合的意图。如果存在其他专用频道，请在其中重复公告。

  2. 确保所有其他存储库维护者都了解以下发布的时间。

发布主要集合版本

假定新版本为 X.0.0。

  1. 确保 galaxy.yml 包含正确的版本号 X.0.0。如果不是这种情况，请创建一个 PR 来更新它。这将导致健全性测试失败，因为必须在 X.0.0 中删除所有弃用，因此这可能需要大量工作，并且应该在主要版本发布前几周完成。

  2. 检查集合中是否存在主要版本中计划删除但健全性测试未报告的弃用。使用过去的变更日志或在存储库中运行 grep -r `X.0.0` plugins/。

  3. 如果要发布 community.general 和 community.network 集合，请在相应的存储库中创建一个新的 backport-X 标签。从相应的现有标签复制样式和描述。

  4. 确保您位于本地分支中的默认分支中。这些示例使用 main。

git status
git checkout main     # if needed

  1. 更新您的本地分支

git pull --rebase upstream main

创建发布分支

  1. 创建一个分支 stable-X。将 X 替换为正确的数字，并将其推送到 上游 存储库，而不是推送到 origin。

git branch stable-X main
git push upstream stable-X

  1. 从 main 分支创建并检出到另一个分支

git checkout -b update_repo

  1. 将分支中 galaxy.yml 中的版本更新为下一个 预期 版本，例如，X.1.0。

创建变更日志

  1. 将 changelogs/changelog.yml 替换为

ancestor: X.0.0
releases: {}

  1. 从 changelogs/fragments/ 中删除所有变更日志片段。删除变更日志片段可确保每个主要版本都有一个变更日志，描述自上次主要版本以来的更改。

  2. 添加并提交所有更改。将分支推送到 origin 存储库。

  3. 在集合存储库中创建一个拉取请求。如果 CI 测试通过，则合并拉取请求，因为 main 分支正在等待下一个次要/主要版本的更改

  4. 切换到 stable-X 分支。

  5. 在 stable-X 分支中，验证 galaxy.yml 是否包含正确的版本号 X.0.0。

  6. 在 stable-X 分支中，确保 changelogs/changelog.yml 包含正确的祖先版本

ancestor: X-1.0.0
releases: {}

  1. 在 stable-X 分支中，添加一个变更日志片段 changelogs/fragments/X.0.0.yml，其内容为

release_summary: |-
  Write some text here that should appear as the release summary for this version.
  The format is reStructuredText, but not a list as for regular changelog fragments.
  This text will be inserted into the changelog.

例如

release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD.

  1. 在 stable-X 分支中，生成变更日志

antsibull-changelog release --cummulative-release

  1. 在 stable-X 分支中，验证 CHANGELOG.rst 的外观是否符合预期。

  2. 在 stable-X 分支中，更新 README.md，以便变更日志链接指向 /tree/stable-X/，而不再指向 /tree/main/，并分别更改徽章，例如，在 AZP 的情况下，将 ?branchName=stable-X 添加到 AZP CI 徽章（https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X）。

  3. 在 stable-X 分支中，添加、提交并将更改推送到 上游 存储库（而不是 origin），包括 README.md、CHANGELOG.rst 和 changelogs/changelog.yaml，以及可能删除/存档的片段。

发布集合

  1. 在 stable-X 分支中，使用集合版本 X.0.0 将带注释的标签添加到最后一次提交。将此标签推送到 upstream 存储库将使 Zuul 在 Ansible Galaxy 上发布该集合。

git tag -n    # see current tags and their comments
git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.0.0"
git push upstream NEW_VERSION

  1. 如果集合使用 Zuul 来发布其版本，请等待新版本发布到集合的 Ansible Galaxy 页面。它将显示在可供下载的 tarball 列表中。

  2. 如果发布 tarball 在推送标签后几个小时内没有出现，请尝试重新标记发布提交并再次推送该标签。在位于发布提交的 stable-X 分支中

git tag --delete NEW_VERSION
git push upstream :NEW_VERSION
git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.0.0"
git push upstream NEW_VERSION

  1. 为新标签添加一个 GitHub 发布。标题应为版本和内容，例如 - 有关所有更改，请参见 https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst。

  2. 通过 Bullhorn 新闻稿 发布此版本。

  3. 在集合的置顶发布问题/社区公告板中和 #ansible-community Matrix/Libera.Chat IRC 频道 中宣布此版本。

  4. 在 stable-X 分支中，将 galaxy.yml 中的版本更新为下一个 预期 版本，例如，X.1.0。添加、提交并推送到 上游 存储库。

发布次要集合版本

假定新版本为 X.Y.0。预计所有应该进入其中的更改都已从默认分支向后移植到 stable-X 分支。

创建变更日志

  1. 在 stable-X 分支中，请确保 galaxy.yml 文件包含正确的版本号 X.Y.0。如果不是，请更新它。

  2. 在 stable-X 分支中，添加一个 changelog 片段 changelogs/fragments/X.Y.0.yml，内容如下：

release_summary: |-
  Write some text here that should appear as the release summary for this version.
  The format is reStructuredText, but not a list as for regular changelog fragments.
  This text will be inserted into the changelog.

  1. 在 stable-X 分支中，运行以下命令：

antsibull-changelog release

  1. 在 stable-X 分支中，验证 CHANGELOG.rst 文件是否符合预期。

  2. 在 stable-X 分支中，将 CHANGELOG.rst 和 changelogs/changelog.yaml 的更改添加、提交并推送到 **上游（upstream）** 仓库，而不是 origin 仓库。同时，可能需要删除/归档片段。

发布集合

  1. 在 stable-X 分支中，使用集合版本 X.Y.0 对最后一次提交添加一个带注释的标签。将此标签推送到 upstream 仓库将使 Zuul 在 Ansible Galaxy 上发布该集合。

git tag -n    # see current tags and their comments
git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.0"
git push upstream NEW_VERSION

  1. 等待新版本发布到集合的 Ansible Galaxy 页面。发布的版本将出现在可供下载的 tar 包列表中。

  2. 为新标签添加一个 GitHub 发布。标题应为版本和内容，例如 - 有关所有更改，请参见 https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst。

  3. 通过 Bullhorn 新闻稿 发布此版本。

  4. 在集合的置顶发布 issue/社区公告栏以及 #ansible-community Matrix/IRC 频道中宣布此版本发布。此外，您可以使用 GitHub 的 Releases 系统宣布此版本。

  5. 在 stable-X 分支中，将 galaxy.yml 中的版本更新为下一个**预期**版本。例如，如果您已发布 X.1.0，则下一个预期版本可能是 X.2.0。添加、提交并推送到 **上游（upstream）** 仓库。

  6. 切换到 main 分支。

  7. 在 main 分支中

  1. 如果在下一个主版本发布之前发布了更多次要版本，也请将 galaxy.yml 中的版本更新为 X.(Y+1).0。创建一个专门的拉取请求并合并。

  2. 如果下一个版本将是一个新的主版本，创建一个拉取请求，在其中将 galaxy.yml 中的版本更新为 (X+1).0.0。请注意，由于计划在 (X+1).0.0 中删除的弃用项，健全性测试很可能会失败，这些弃用项会被测试标记出来。

对于每个此类弃用项，请决定：

  • 是否立即删除它们。例如，您可以删除整个 modules/plugins 或删除重定向。

  • 是否将忽略条目添加到相应的 tests/sanity/ignore-*.txt 文件并创建 issue，例如针对 modules/plugins 中删除的功能。

一旦 CI 测试通过，请合并拉取请求。请确保此拉取请求在发布后不久合并，以避免 version_added 健全性测试对新功能拉取请求期望错误的版本。

注意

在发布前的几天进行一些删除是有意义的。这些删除必须在 main 分支中进行，并且不能向后移植。

发布补丁版本

假设新版本为 X.Y.Z，之前的补丁版本为 X.Y.z，其中 z < Z。z 通常为 0，因为补丁版本不常见。

在预期更多次要版本时发布

  1. 检出 X.Y.z 标签。

  2. 更新 galaxy.yml，使版本为 X.Y.Z。添加并提交。

  3. 从 stable-X 中拣选（cherry-pick） X.Y.z 之后添加的所有更改，这些更改应该进入 X.Y.Z。

  4. 添加一个 changelog 片段 changelogs/fragments/X.Y.Z.yml，内容如下：

release_summary: |-
  Write some text here that should appear as the release summary for this version.
  The format is reStructuredText but not a list as for regular changelog fragments.
  This text will be inserted into the changelog.

添加到 Git 并提交。

  1. 生成 changelogs。

antsibull-changelog release

  1. 验证 CHANGELOG.rst 文件是否符合预期。

  2. 将对 CHANGELOG.rst 和 changelogs/changelog.yaml 的更改，以及可能已删除/归档的片段添加并提交。

发布集合

  1. 使用集合版本 X.Y.Z 对最后一次提交添加一个带注释的标签。将此标签推送到 upstream 仓库将使 Zuul 在 Ansible Galaxy 上发布该集合。

git tag -n    # see current tags and their comments
git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.1"
git push upstream NEW_VERSION

  1. 等待新版本发布到集合的 Ansible Galaxy 页面。它将出现在可供下载的 tar 包列表中。

  2. 为新标签添加一个 GitHub 发布。标题应为版本和内容，例如 - 有关所有更改，请参见 https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst。

注意

此版本的更改数据仅包含在标签中，而不包含在分支中，特别是 stable-X 中。这是故意的，因为下一个次要版本 X.(Y+1).0 已经包含了 X.Y.Z 的更改，因为这些更改是从 stable-X 中拣选出来的。

  1. 通过 Bullhorn 新闻稿 发布此版本。

  2. 在集合的置顶发布 issue/社区公告栏以及 #ansible-community Matrix/IRC 频道 <https://docs.ansible.org.cn/ansible/devel/community/communication.html#real-time-chat> 中宣布此版本发布。

在不预期更多次要版本时发布

  1. 在 stable-X 分支中，请确保 galaxy.yml 文件包含正确的版本号 X.Y.Z。如果不是，请更新它！

  2. 在 stable-X 分支中，添加一个 changelog 片段 changelogs/fragments/X.Y.Z.yml，内容如下：

release_summary: |-
  Write some text here that should appear as the release summary for this version.
  The format is reStructuredText, but not a list as for regular changelog fragments.
  This text will be inserted into the changelog.

  1. 在 stable-X 分支中生成 changelogs。

antsibull-changelog release

  1. 在 stable-X 分支中，验证 CHANGELOG.rst 文件是否符合预期。

  2. 在 stable-X 分支中，将 CHANGELOG.rst 和 changelogs/changelog.yaml 的更改添加、提交并推送到 **上游（upstream）** 仓库，而不是 origin 仓库。同时，可能需要删除/归档片段。

发布集合

  1. 在 stable-X 分支中，使用集合版本 X.Y.Z 对最后一次提交添加一个带注释的标签。将此标签推送到 upstream 仓库将使 Zuul 在 Ansible Galaxy 上发布该集合。

git tag -n    # see current tags and their comments
git tag -a NEW_VERSION -m "comment here"    # the comment can be, for example, "community.foo: 2.1.1"
git push upstream NEW_VERSION

  1. 等待新版本发布到集合的 Ansible Galaxy 页面。它将出现在可供下载的 tar 包列表中。

  2. 为新标签添加 GitHub 发布。标题应为版本和内容，例如：查看 https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst 了解所有更改。

  3. 通过 Bullhorn 新闻稿 发布此版本。

  4. 在集合的置顶 issue/社区公告栏以及 #ansible-community Matrix/IRC 频道中宣布此版本发布。