集合的变更日志¶

antsibull-changelog 工具允许您创建和更新 Ansible 集合的变更日志，这些变更日志类似于早期版本 Ansible 自身提供的变更日志，并且与组合的 Ansible 社区发行版变更日志兼容。

以下说明假设 antsibull 已正确安装，例如通过 pip install antsibull-changelog。这是安装 antsibull-changelog 的首选方法。

如果您想获取当前的 main 分支（包含尚未发布的更改），请运行 pip install https://github.com/ansible-community/antsibull-changelog/archive/main.tar.gz。如果您克隆了 git 仓库并希望使用 poetry 从那里运行它，则必须将 antsibull-changelog 替换为 poetry run antsibull-changelog。

为集合引导变更日志¶

要设置 antsibull-changelog，请运行

antsibull-changelog init /path/to/your/collection

这是包含 galaxy.yml 的目录。这将创建子目录 changelogs/ 和 changelogs/fragments/，以及配置文件 changelogs/config.yaml。根据您的需要调整配置文件。最感兴趣的设置是

title：默认情况下，这是集合的命名空间和名称的首字母大写。您可以随意在此处插入更友好的名称。
output_formats：默认情况下为 [rst]。将其更改为 [rst, md] 以输出 RST 和 MarkDown 版本的变更日志，或更改为 [md] 以仅输出 MarkDown 版本。
keep_fragments：默认值 false 在发布完成后会删除片段文件。如果您希望保留旧版本的片段文件，请将其设置为 true。如果您想在发布后删除片段，但将其存档到另一个目录，您可以结合使用 archive_path_template 选项和 keep_fragments: no。请参见下面列表中的用法。
changelog_filename_template：默认值 ../CHANGELOG.rst 相对于 changelogs/ 目录。
use_fqcn：默认值 true 在提及新的插件和模块时使用 FQCN。
flatmap：设置为 true 或 false 将显式启用或禁用 flatmapping。由于 flatmapping 默认情况下是禁用的（ansible-core/-base 除外），因此这实际上仅适用于大型社区集合 community.general 和 community.network。
always_refresh：请参阅 "更新/刷新 changelog.yaml" 以了解如何刷新变更日志片段和/或插件说明。
archive_path_template：如果 keep_fragments 设置为 false，并且设置了 archive_path_template，则片段将被复制到 archive_path_template 指定的目录中，而不是被删除。如果该目录不存在，则会创建它。占位符 {version} 可用于将片段包含其中的当前集合版本。

有关所有配置设置的说明，请参阅单独的文档 antsibull-changelog 的配置设置。

验证变更日志片段¶

如果您想对变更日志片段进行基本的语法检查，您可以运行

antsibull-changelog lint

如果您想检查特定片段，您可以提供其路径；否则，将检查 changelogs/fragments/ 中的所有片段。这可以在 CI 中使用，以避免贡献者签入无效的变更日志片段，或引入新的部分（通过错打现有部分的名称，或只是猜测错误的名称）。

如果 antsibull-changelog lint 在 stdout 上不产生输出，并以退出代码 0 退出，则变更日志片段正常。如果发现错误，则每个错误都会在 stdout 上报告一行，格式为 path/to/fragment:line:column:message，程序将以退出代码 3 退出。其他退出代码表示命令行或在执行 linter 期间出现问题。

发布集合的新版本¶

要发布集合的新版本，您需要运行

antsibull-changelog release

在您的集合树中。这假设 galaxy.yml 存在，并且其版本是您要发布的版本的版本。如果该文件不存在，或者 version 的值错误，您可以明确指定要发布的版本

antsibull-changelog release --version 1.0.0

如果您不想要默认值（今天），还可以使用 --date 2020-12-31 指定发布日期。

在进行发布时，变更日志生成器将读取变更日志中尚未提及的所有变更日志片段，并将它们包含在 changelogs/changelog.yaml 中的新条目中。它还将扫描集合所有模块和插件的元数据，并将所有 version_added 等于此版本的模块和插件作为新模块/插件提及。

模块和插件的元数据存储在 changelogs/.plugin-cache.yaml 中，并且仅在发布版本更改后重新计算。要强制重新收集这些数据，请删除该文件，或将 --reload-plugins 选项指定给 antsibull-changelog release。该文件**不应**添加到源代码控制中。我们建议将其添加到您的 .gitignore 文件中，或者如果您使用其他源代码控制，则使用等效机制。

运行 antsibull-changelog release 后，您应该检查 changelogs/changelog.yaml 和生成的 reStructuredText 文件（默认为 CHANGELOG.rst）。

更新/刷新 changelog.yaml¶

默认情况下，changelogs/changelog.yaml 文件是 antsibull-changelog 的主要事实来源。它只在发布新版本时修改，在这种情况下，除了当前版本之外的其他版本的现有条目不会被触及。

如果主要的事实来源应该是片段或插件源，则必须使用刷新选项或配置。

请注意，对于插件，会在 changelogs/.plugin-cache.yaml 中创建缓存。当运行 generate 和 release 子命令时，并且最新版本（对于 generate）或发布版本（对于 release）与缓存文件中记录的版本不同时，会更新此缓存。可以通过指定 --reload-plugins 选项来强制重新生成。

另请注意，刷新插件会清除变更日志片段添加的所有插件。

这意味着如果要更新插件说明，则必须删除插件缓存，或者除了刷新选项/配置之外，还必须指定 --reload-plugins。刷新可以通过不同的方式配置，可以通过 always_refresh 配置设置或三个命令行选项 --refresh、--refresh-plugins 和 --refresh-fragments 来配置。这些可以为 generate 和 release 子命令指定。

always_refresh 配置是一个字符串，包含以下值之一
none（默认）：等效于未指定 --refresh-plugins、--refresh-fragments 和 --refresh；
full：等效于指定了 --refresh-plugins allow-removal --refresh-fragments with-archives，或者等效于 --refresh；
逗号分隔的列表，其中支持以下条目
- plugins：等效于指定了 --refresh-plugins allow-removal；
- plugins-without-removal：等效于指定了 --refresh-plugins prevent-removal；
- fragments：等效于指定了 --refresh-fragments with-archives；
- fragments-without-archives：等效于指定了 --refresh-fragments without-archives。
--refresh 命令行参数等效于 --refresh-plugins allow-removal --refresh-fragments with-archives。
--refresh-plugins：如果指定，则插件和模块说明将从插件缓存更新。
allow-removal（默认）：插件和模块说明已更新。如果缓存中不存在模块或插件，它将从变更日志中**删除**。请注意，如果您没有为集合的每个主要版本启动新的变更日志，并且之前已删除插件或模块，则 --refresh plugins allow-removal 将删除这些插件或模块添加时的早期变更日志条目！
prevent-removal：插件和模块说明已更新。如果缓存中不存在模块或插件，它将**不会**从变更日志中删除。
--refresh-fragments：如果指定，则所有版本的片段将从变更日志片段文件重新创建。只有在 keep_fragments 为 true 或存在片段存档（请参阅 archive_path_template 选项）时才有可能。请注意，如果并非所有片段都被存档或保存在片段目录中，它们将从变更日志中**删除**。
with-archives（默认）：使用存档和当前片段目录来更新片段。
without-archives：仅使用当前片段目录来更新片段。已移至存档且不再存在于片段目录中的片段将从变更日志中消失。

变更日志片段类别¶

本节描述在默认配置中创建的部分类别。您可以更改它们，但这对于将包含在 Ansible 社区发行版中的集合来说是强烈不建议的。

这些类别与 Ansible 案例变更日志片段中的类别相同。

注意

变更日志生成器会自动检测新的模块和可记录的新插件（即，您在其中有 DOCUMENTATION 和 version_added 的地方），因此您无需为它们创建变更日志条目。

类别的完整列表是

release_summary

这是一个特殊章节：与字符串列表相反，它接受一个字符串。此字符串将插入当前版本变更日志条目的顶部，位于任何章节之前。只有一个包含release_summary章节的片段。在ansible-core中，这用于声明发布日期并链接到移植指南（示例，结果）。

breaking_changes

此（新的）类别应列出所有需要用户在升级时特别注意的功能更改，因为现有行为已更改。这主要是在 Ansible 的移植指南中描述的内容。根据语义版本控制，此部分应仅出现在初始主要版本 (x.0.0) 中。

major_changes

此类别包含对集合的主要更改。每个主要版本中只应包含少量项目，描述高级别的更改。根据语义版本控制，此部分不应出现在补丁版本中。

minor_changes

此类别应提及所有新功能，例如插件或模块选项。根据语义版本控制，此部分不应出现在补丁版本中。

removed_features

此类别应提及此版本中已删除的所有模块、插件和功能。根据语义版本控制，此部分应仅出现在初始主要版本 (x.0.0) 中。

deprecated_features

此类别应包含所有已弃用并在未来版本中将被删除的模块、插件和功能。根据语义版本控制，此部分不应出现在补丁版本中。

security_fixes

此类别应提及所有与安全相关的修复，包括可用的 CVE。

bugfixes

此类别应列出所有修复先前版本中存在的错误的错误修复。

known_issues

此类别应提及当前未修复或将不会修复的已知问题。

trivial

此类别将不会显示在变更日志中。它可以用来描述未触及用户界面代码的更改，例如测试中的更改。如果每个 PR 都需要一个变更日志片段，这将非常有用。

有一些以add开头的特殊类别；请参阅下一节了解更多详情。

示例¶

如何在 Ansible 文档中找到编写变更日志片段的指南 Ansible 文档。

常规变更日志片段示例

bugfixes:
  - docker_container - wait for removal of container if docker API returns early
    (https://github.com/ansible/ansible/issues/65811).

在这种情况下，文件名是changelogs/fragments/65854-docker_container-wait-for-removal.yml，因为这是在ansible/ansible 中的 PR #65854中实现的。

一个片段也可以包含多个部分，或一个部分中的多个条目

deprecated_features:
- docker_container - the ``trust_image_content`` option will be removed. It has always been ignored by the module.
- docker_stack - the return values ``err`` and ``out`` have been deprecated. Use ``stdout`` and ``stderr`` from now on instead.

breaking_changes:
- "docker_container - no longer passes information on non-anonymous volumes or binds as ``Volumes`` to the Docker daemon. This increases compatibility with the ``docker`` CLI program. Note that if you specify ``volumes: strict`` in ``comparisons``, this could cause existing containers created with docker_container from Ansible 2.9 or earlier to restart."

release_summary部分很特殊，因为它不包含字符串列表，而是一个字符串，并且在一个版本的变更日志中只能显示一个这样的条目。通常对于每个版本（预发布版或常规版本），最多添加一个包含release_summary的片段，这只能由发布者完成。release_summary应包含有关发布的一些全局信息；例如，在Ansible 的变更日志中，它总是提及发布日期并链接到移植指南。

包含release_summary的片段示例可能是community.general 中的changelogs/fragments/0.2.0.yml

release_summary: |
  This is the first proper release of the ``community.general`` collection on 2020-06-20.
  The changelog describes all changes made to the modules and plugins included in this collection since Ansible 2.9.0.

添加新的角色、剧本、测试和过滤器插件¶

请注意，使用 ansible-core 2.11+，如果其文档（在参数规范中）包含main入口点的适当version_added值，则会自动检测新的角色。使用 ansible-core 2.14+（或当前的devel和milestone分支），如果其文档包含适当的version_added值，也会自动检测过滤器和测试插件。没有 ansible-core 版本允许记录剧本（尚未），因此必须按如下所述记录新的剧本。

以下描述了记录新剧本的方法。在生成变更日志的发布期间使用旧版本的 ansible-core 时，这也可以用于记录新的角色、测试插件和过滤器插件。这通过使用名称以add开头的变更日志片段中的特殊部分来实现。

---
# Always needed for new playbooks:
add object.playbook:
  - name: wipe_server
    description: Wipes a server

# Only needed when ansible-core < 2.14 is used during the release process,
# or when the filter has no documentation or the documentation is missing a
# 'version_added' entry:
add plugin.filter:
  - name: to_time_unit
    description: Converts a time expression to a given unit
  - name: to_seconds
    description: Converts a time expression to seconds

# Only needed when ansible-core < 2.14 is used during the release process,
# or when the test has no documentation or the documentation is missing a
# 'version_added' entry:
add plugin.test:
  - name: asn1time
    description: Check whether the given string is an ASN.1 time

# Only needed when ansible-core < 2.11 is used during the release process,
# or when the role has no argument spec or the argument spec is missing a
# 'version_added' entry for the 'main' entrypoint:
add object.role:
  - name: nginx
    description: A nginx installation role

移植指南条目¶

以下部分被视为集合的移植指南。对于包含在 Ansible 中的集合，这些内容将插入到 Ansible 的移植指南中。

major_changes
breaking_changes
deprecated_features
removed_features