将 Ansible 内容迁移到不同的集合

您可能决定将内容从一个集合迁移到另一个集合；例如，要从 community.general 或 community.network 中提取一组相关模块以创建更集中的集合。当您在集合之间迁移内容时，您必须采取某些步骤以确保用户能够跟踪过渡。

迁移内容 

如果要从中迁移内容的集合包含在 Ansible 社区包中，请确保目标集合满足 Ansible 社区包集合要求。满足要求后，您可以按如下方式迁移内容

将内容从源（旧）集合复制到目标（新）集合。
更改 M()、示例、seealso、extended_documentation_fragments 以在移动的内容、旧集合以及其他对内容有引用的集合中使用实际的 FQCN。
移动所有相关问题、拉取请求和维基页面。
浏览 ansible-documentation GitHub 仓库的 docs/docsite 目录（例如，使用 grep 命令行实用程序）以检查是否存在使用已移动模块和插件的示例，以便您可以更新这些 FQCN。
使用 removal_version 弃用模块/插件，该版本计划在旧集合的 meta/runtime.yml 中的下一个主要版本中使用。在将复制的内容包含在新集合的版本中之后，必须发布弃用。
当准备发布旧集合的下一个主要版本时

从旧集合中删除模块/插件

删除存储在 plugin/modules 目录中的符号链接（如果适用）（主要是从 community.general 和 community.network 中删除时）

删除相关的单元和集成测试

删除特定模块实用程序（如果它们没有被其他模块/插件或 module_utils 使用）

如果旧集合中有任何特定文档片段，请删除它们

添加包含 removed_features 和 breaking_changes 条目的更改日志片段；您可以在此拉取请求中看到更改日志片段的示例

更改旧集合中的 meta/runtime.yml

将 redirect 添加到相应模块/插件的条目中

特别是，如果适用，为已删除的模块实用程序和文档片段添加 redirect

从那里删除 removal_version

如果存在，则从 tests/sanity/ignore.txt 文件中删除相关条目

删除尚未成为更改日志一部分的已删除内容的相关更改日志片段（换句话说，不要修改 changelogs/changelog.yaml，也不要删除其中提到的文件）

从 tests/unit/requirements.txt、tests/requirements.yml 和 galaxy.yml 中删除不再需要的需求

要实现这些更改，您至少需要创建三个 PR

针对新集合创建 PR 以复制内容。
在旧集合中弃用模块/插件。
稍后根据计划针对旧集合创建 PR 以删除内容。

将内容添加到新集合 

在新集合中创建 PR 以

从旧集合中复制所有相关文件。
如果它是一个操作插件，请包括带有文档的相应模块。
如果它是一个模块，请检查它是否具有相应的操作插件，该插件应该与它一起移动。
如果存在，请检查 meta/ 以了解对 runtime.yml 的相关更新。
仔细检查已移动的 tests/integration 和 tests/units 并更新 FQCN。
查看旧集合中的 tests/sanity/ignore-*.txt 条目。
更新旧集合中的 meta/runtime.yml。

从旧集合中删除内容 

针对源集合仓库创建 PR 以删除与该迁移相关的模块、module_utils、插件和 docs_fragments

如果要删除操作插件，请删除包含文档的相应模块。
如果要删除模块，请删除任何应该与它保持在一起的相应操作插件。
从 meta/runtime.yml 中删除有关已删除插件的任何条目。确保将它们添加到新仓库中。
从 tests/sanity/ignore\*.txt 中删除健全性忽略行
从 tests/integrations/targets/ 中删除相关的集成测试，并从 tests/units/plugins/ 中删除单元测试。
如果要从 community.general 或 community.network 中删除内容，请从 .github/BOTMETA.yml 中删除条目。
仔细查看 meta/runtime.yml 中您可能需要删除或更新的任何条目，尤其是已弃用的条目。
更新 meta/runtime.yml 以包含指向每个插件的重定向，指向新的集合名称。

警告

旧集合的维护者必须确保以不破坏用户体验和语义版本控制的方式合并 PR

包含已合并 PR 的新版本不能在将内容移动到的集合再次发布之前发布，并且其中包含该内容。否则，重定向将无法正常工作，依赖该内容的用户会遇到故障。
一旦删除了内容的集合的 1.0.0 版本发布，此类 PR 只能针对新的**主要**版本合并（换句话说，2.0.0、3.0.0 等）。

更新 BOTMETA.yml 

例如在 community.general 集合仓库中，BOTMETA.yml 是以下内容的真实来源：

ansibullbot

如果旧集合和/或新集合具有 ansibullbot，则必须相应地更新其 BOTMETA.yml。

Ansibulbot 将知道如何将现有问题和 PR 重定向到新仓库。docs.ansible.com 的构建过程将知道在何处查找模块文档。

$modules/monitoring/grafana/grafana_plugin.py:
    migrated_to: community.grafana
$modules/monitoring/grafana/grafana_dashboard.py:
    migrated_to: community.grafana
$modules/monitoring/grafana/grafana_datasource.py:
    migrated_to: community.grafana
$plugins/callback/grafana_annotations.py:
    maintainers: $team_grafana
    labels: monitoring grafana
    migrated_to: community.grafana
$plugins/doc_fragments/grafana.py:
    maintainers: $team_grafana
    labels: monitoring grafana
    migrated_to: community.grafana

示例 PR

对于每个文件，必须显式添加migrated_to: 键。您不能在目录级别添加 migrated_to。这样做是为了允许模块和插件的网络文档重定向到新的集合文档。
对于每个
- 模块
- 插件
- module_utils
- contrib/inventory 脚本
必须添加migrated_to:。
- 您不需要为以下内容添加 migrated_to：
- 单元测试
- 集成测试
- ReStructured Text 文档（docs/docsite/rst/ 下的任何内容）

在 ansible/ansible:devel 中从未存在的文件

使用 Ansible 集合: 另请参见
了解如何安装和使用集合。: 为 Ansible 维护的集合做出贡献
为选定集合做出贡献的指南: 邮件列表
开发邮件列表: 实时聊天

将 Ansible 内容迁移到不同的集合

迁移内容

将内容添加到新集合

从旧集合中删除内容

更新 BOTMETA.yml

迁移内容 

将内容添加到新集合 

从旧集合中删除内容 

更新 BOTMETA.yml 