Ansible 模块或插件的生命周期

Ansible 主仓库中的模块和插件拥有定义的生命周期，从首次引入到最终移除。模块和插件的生命周期与 Ansible 发布周期 <release_cycle> 挂钩。一个模块或插件可能会经历以下四个阶段：

当一个模块或插件首次被 Ansible 接受时，我们将其视为“技术预览（tech preview）”阶段，并在文档中予以标注。
如果模块或插件趋于成熟，文档中的“预览”标记将被移除。这些模块和插件的向后兼容性会得到维持但不能保证，这意味着它们的参数应保持稳定的含义。
如果模块或插件的目标 API 发生了剧烈变化，或者有人创建了更好的功能实现，我们可能会将其标记为“弃用（deprecated）”。被弃用的模块和插件仍然可用，但它们正处于生命周期的末端。我们会将弃用的模块和插件保留 4 个发布周期，并提供弃用警告，以帮助用户更新使用它们的剧本（playbooks）和角色（roles）。
当一个模块或插件被弃用四个发布周期后，它将被移除，并在路由配置中用一个“墓碑（tombstone）”条目代替。被移除的模块和插件将不再随 Ansible 一起发布。墓碑条目旨在帮助用户找到替代的模块和插件。

对于集合中的模块和插件，生命周期类似。自 ansible-base 2.10 起，不再能够将模块标记为“预览”或“稳定”。

在 Ansible 主仓库中弃用模块和插件

要在 ansible-core 中弃用一个模块，您必须：

重命名文件使其以 _ 开头，例如，将 old_cloud.py 重命名为 _old_cloud.py。这样可以保持模块可用，并在模块索引页面将其标记为已弃用。
在相关的变更日志（changelog）中提及此次弃用（通过创建一个包含 deprecated_features 节的变更日志片段）。
在相关的 porting_guide_core_x.y.rst 中引用此次弃用。
在文档中添加 deprecated: 及其以下子值：

removed_in:

一个 string，例如 "2.10"；即该模块将被替换为仅含文档的模块存根（stub）的 Ansible 版本。通常为当前版本 +4。与 removed_at_date: 互斥。

removed_at_date:

(新增于 ansible-base 2.10)。一个 ISO 8601 格式的日期，表示模块将被移除的时间。通常为模块弃用之日起 2 年后。与 removed_in: 互斥。

why:

可选字符串，用于详细说明移除原因。

alternatives:

告知用户应该采取的替代方案，例如：Use M(whatmoduletouseinstead) instead.（请改用 M(whatmoduletouseinstead)）。

关于文档化弃用的示例，请参阅此弃用多个模块的 PR。该 PR 中的某些元素现在可能已过时。

在集合中弃用模块和插件

要在集合中弃用一个模块，您必须：

在 meta/runtime.yml 的 plugin_routing 中添加一个 deprecation 条目。例如，要弃用模块 old_cloud，请添加：
```
plugin_routing:
    modules:
        old_cloud:
            deprecation:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.
```
对于其他插件类型，您需要将 modules: 替换为 <plugin_type>:，例如查找插件使用 lookup:。弃用动作插件（action plugins）时，需要添加两个条目：一个用于动作插件，一个用于包含文档的模块文件。

除了 removal_version，您还可以使用 removal_date 配合 ISO 8601 格式的日期，该日期之后模块将在集合的新主版本中被移除。
在相关的变更日志中提及此次弃用。如果集合使用 antsibull-changelog，请创建一个包含 deprecated_features 节的变更日志片段。
在模块或插件的文档中添加 deprecated: 及其以下子值：

removed_in:

一个 string，例如 "2.10"；即该模块将被替换为仅含文档的模块存根（stub）的 Ansible 版本。通常为当前版本 +4。与 removed_at_date: 互斥。

removed_at_date:

(新增于 ansible-base 2.10)。一个 ISO 8601 格式的日期，表示模块将被移除的时间。通常为模块弃用之日起 2 年后。与 removed_in: 互斥。

why:

用于详细说明移除原因的字符串。

alternative:

告知用户应该采取的替代方案，例如：Use M(whatmoduletouseinstead) instead.。有关引用模块以外实体的方法，请参阅模块文档内部链接。

在 Ansible 主仓库中更改模块或插件名称

您还可以通过使用以 _ 开头的符号链接（symlink）来重命名模块并保留指向旧名称的弃用别名。此示例允许使用 fileinfo 来调用 stat 模块，从而使以下示例等效：

ln -s stat.py _fileinfo.py
ansible -m stat -a "path=/tmp" localhost
ansible -m fileinfo -a "path=/tmp" localhost

在集合中重命名模块或插件，或将模块或插件重定向到另一个集合

要在集合中重命名模块或插件，或将模块或插件重定向到另一个集合，您需要在 meta/runtime.yml 的 plugin_routing 中添加一个 redirect 条目。例如，要将模块 old_cloud 重定向到 foo.bar.new_cloud，请添加：

plugin_routing:
    modules:
        old_cloud:
            redirect: foo.bar.new_cloud

如果您想弃用旧名称，请添加 deprecation: 条目（见上文）。

plugin_routing:
    modules:
        old_cloud:
            redirect: foo.bar.new_cloud
            deprecation:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.

您需要使用新模块/插件名称的全限定集合名称 (FQCN)，即使它位于与重定向相同的集合中。通过使用另一个集合的 FQCN，您可以将模块/插件重定向到该集合。

如果您需要支持 Ansible 2.9，请注意 Ansible 2.9 无法识别 meta/runtime.yml。在 Ansible 2.9 中，您仍然可以通过使用符号链接在一个集合内部重命名插件和模块。请注意，ansible-base 2.10、ansible-core 2.11 及更新版本将优先使用 meta/runtime.yml 条目而非符号链接。

在集合中为模块或插件创建墓碑记录

要从集合中移除一个已弃用的模块或插件，您需要为其创建墓碑记录：

删除模块或插件文件以及相关的测试、文档引用和文档文件。
在 meta/runtime.yml 中添加墓碑条目。例如，要为模块 old_cloud 创建墓碑记录，请添加：
```
plugin_routing:
    modules:
        old_cloud:
            tombstone:
                removal_version: 2.0.0
                warning_text: Use foo.bar.new_cloud instead.
```
除了 removal_version，您还可以使用 removal_date 配合 ISO 8601 格式的日期。该日期应为下一个主版本发布的日期。