antsibull-changelog 配置设置¶
本文档描述了 `changelogs/config.yaml` 文件中支持的所有设置。
常规选项¶
`add_plugin_period` (布尔值)¶
对于现有配置，默认值为 `false`；对于新配置，默认值为 `true`。
如果设置为 `false`，则使用插件简短描述。如果设置为 `true`，则如果插件简短描述末尾没有其他标点符号，则在末尾添加句点。设置为 `true` 符合Ansible 变更日志格式。
`always_refresh` (字符串)¶
允许的值为 `none`、`full` 或 `plugins`、`plugins-without-removal`、`fragments` 和 `fragments-without-archives` 中一个或多个的逗号分隔组合。
如果传递 `true`，则将其转换为 `full`。如果传递 `false`，则将其转换为 `none`。
详情请参见主要文档中的"更新/刷新 changelog.yaml"。
`archive_path_template` (可选字符串)¶
默认值为 `null`。
当 `keep_fragments` 设置为 `false` 且此设置已定义时，在发布后，片段将复制到此设置指定的路径。此设置假定指向一个目录，可以使用占位符 `{version}` 使目标取决于新版本的版本号。如果目录尚不存在，则会创建它。
`changelog_filename_template` (字符串)¶
对于现有配置，默认值为 `CHANGELOG-v%s.rst`；对于新配置，默认值为 `../CHANGELOG.rst`。
这是相对于 `changelogs/` 目录的路径，用于写入变更日志的 reStructuredText 版本。占位符 `%s` 将被版本的第一个 `changelog_filename_version_depth` 部分替换。
注意
文件扩展名（默认为 `.rst`）将始终被与输出格式匹配的扩展名替换（请参见`output_formats`）。因此，此处提供的扩展名将始终被忽略。
`changelog_filename_version_depth` (整数)¶
对于现有配置，默认值为 2；对于新配置，默认值为 0。
确定在 `changelog_filename_template` 中替换 `%s` 时要使用的当前发行版本的组成部分的数量（见上文）。对于值 2，版本 1.2.3 将产生字符串 `1.2`。值为 0 将产生空字符串。
`changes_file` (字符串)¶
对于现有配置，默认值为 `.changes.yaml`；对于新配置，默认值为 `changelog.yaml`。
以机器可读形式存储变更日志的 YAML 文件。此文件相对于 `changelogs/` 目录，不应更改，因为 `changelogs/changelog.yaml` 是机器可读文件的标准位置，Ansible 社区发行版变更日志生成器预期该文件存在。
`changes_format` (字符串)¶
必须设置为 `combined`。
所有片段和插件数据都存储在文件中（由 ansible-base、ansible-core 和集合使用）。
请注意，对 `classic` 的支持已被 **移除**，此字段现在是必需的。
`changelog_nice_yaml` (布尔值)¶
默认为 `false`。
当设置为 `true` 时，`changelogs/changelog.yaml` 文件将使用与 ansible-lint 的默认规则兼容的略微不同的 YAML 编码写入。
注意
如果 ansible-lint 的新版本调整了它们的 yamllint 配置，则将来可能会调整使用的确切格式。
`changelog_sort` (字符串)¶
默认为 `alphanumerical`。
此选项控制 `changelogs/changelog.yaml` 中变更日志条目的排序。它接受以下值：
- `unsorted`：不对变更日志条目进行排序。条目按添加顺序存储。
- `version`：按版本升序对变更日志条目进行排序。
- `version_reversed`：按版本降序对变更日志条目进行排序。
- `alphanumerical`：按字母数字顺序对变更日志条目进行排序。
`flatmap` (可选布尔值)¶
默认值为 `null`。
可以显式设置为 `true` 或 `false` 以启用或禁用 flatmapping。由于 flatmapping 默认情况下是禁用的（ansible-core 除外），因此这实际上只需要用于大型社区集合 `community.general` 和 `community.network`。
启用后，插件 `foo.bar.subdir.dir.plugin_name` 将被提及为 `plugin_name` 或 `foo.bar.plugin_name`（如果 `use_fqcn` 为 `true`），而不是 `subdir.dir.plugin_name` 或 `foo.bar.subdir.dir.plugin_name`。
`is_other_project` (布尔值)¶
默认值为 `false`。
如果设置为 `true`，则不查找 `galaxy.yml`，也不查找新的 Ansible 对象（插件、模块和角色）。这允许将变更日志生成器用于不是 ansible-core/-base 或 Ansible 集合的项目。
`ignore_other_fragment_extensions` (布尔值)¶
对于现有配置，默认值为 `false`；对于新配置，默认值为 `true`。
如果设置为 `true`，则仅考虑不以点开头的 `.yml` 和 `.yaml` 片段文件名。这与 `ansible-test sanity --test changelog` 强制执行的内容兼容。如果设置为 `false`（如果未指定则为默认值），则考虑所有不以点开头的文件名。
`keep_fragments` (布尔值)¶
默认值为 `false`。
如果设置为 `false`，则在发布后将删除片段文件。如果设置为 `true`，则保留旧版本的片段文件。
如果应在发布后将片段文件移动到另一个目录，请将此设置设置为 `false` 并设置 `archive_path_template`。
另请参见 `prevent_known_fragments`。
`mention_ancestor` (布尔值)¶
默认值为 `true`。
如果在 `changelogs/changelog.yaml` 中定义了祖先，则确定是否应在变更日志开头提及它。如果设置为 `true`，则会在变更日志顶部插入 `此变更日志描述版本 {ancestor} 之后所做的更改`。
`notes_dir` (字符串)¶
默认值为 `fragments`。
包含变更日志片段的 `changelogs/` 子目录的名称。
`output_formats` (字符串列表)¶
默认为 `["rst"]`。
要将变更日志写入的输出格式列表。支持的格式有 `rst`（用于 ReStructuredText）和 `md`（用于 MarkDown）。
`prelude_name` (字符串)¶
默认值为 `release_summary`。
要在变更日志片段中使用的序言部分的名称。此部分是特殊的，因为它不接受列表，而接受字符串。
`prelude_title` (字符串)¶
默认值为 `Release Summary`。
名称在 `prelude_name` 中设置的部分的标题。
prevent_known_fragments（可选布尔值）¶
默认值与keep_fragments选项的值相同。
如果设置为true，则不会将变更日志片段添加到过去已使用过其文件名的版本中。这是 antsibull-changelog 0.9.0 之前的默认行为。从 0.9.0 开始，如果keep_fragments设置为false，则其默认值也为false。
如果稍后将keep_fragments设置为false，而一些来自旧版本的片段仍然存在，并且您希望保留它们，请确保将prevent_known_fragments显式设置为true。否则，它们将再次添加到下一个版本中。
sanitize_changelog（布尔值）¶
对于现有配置，默认值为 `false`；对于新配置，默认值为 `true`。
加载changelogs/changelog.yaml文件时，删除所有无效和多余的信息。
sections（由两个字符串元素组成的列表）¶
默认值为：
- - major_changes
- Major Changes
- - minor_changes
- Minor Changes
- - breaking_changes
- Breaking Changes / Porting Guide
- - deprecated_features
- Deprecated Features
- - removed_features
- Removed Features (previously deprecated)
- - security_fixes
- Security Fixes
- - bugfixes
- Bugfixes
- - known_issues
- Known Issues
列出所有章节名称（第一个元素）及其标题（第二个元素）。此处未列出的两个章节是序言章节（release_summary / “版本摘要”）和琐碎章节（trivial，无标题）。
不建议更改此列表，除非可能调整章节标题。使用其他章节名称的集合将导致 Ansible 社区发行版变更日志生成出现问题。
title（字符串）¶
默认值为集合的命名空间和名称的首字母大写形式。
标题显示在变更日志的顶部。
trivial_section_name（可选字符串）¶
对于集合和其他项目，默认值为trivial；对于 ansible-core/ansible-base，默认值为null。
这定义了一个未包含在生成的 reStructuredText 版本变更日志中的章节。它可以用来添加变更日志片段到那些过于琐碎（trivial）而不应出现在变更日志中，或与用户无关的更改（例如，使用的 CI 系统中的更改）。当设置为null时，不允许使用琐碎章节。
use_fqcn（布尔值）¶
对于现有配置，默认值为 `false`；对于新配置，默认值为 `true`。
当设置为true时，在提及新的插件和模块时使用 FQCN（完全限定集合名称）。这意味着namespace.name.将分别添加到插件和模块名称的前面。
vcs（可选字符串）¶
允许的值为none、git或auto。对于现有配置，默认值为none；对于新配置，默认值为auto。
配置项目是否使用版本控制系统。目前，这在（重新）加载 Ansible 集合的插件列表时使用。为此，项目文件将被复制到一个临时目录树中，以便可以使用ansible-doc提取插件文档。
当设置为none时，将考虑项目目录中的所有文件。当设置为git时，将使用git ls-files来确定要考虑哪些文件（git忽略的目录和文件将被忽略）。当设置为auto时，将自动检测项目是否属于 Git 存储库。
已弃用的选项¶
new_plugins_after_name（字符串）¶
默认值为''（空字符串）。
此设置未使用。
Ansible-core/-base 特定选项¶
这些选项仅用于 ansible-core 的变更日志，即 ansible/ansible GitHub 存储库中的变更日志。
use_semantic_versioning（布尔值）¶
默认值为 `false`。
如果设置为true，则假定 ansible-core 使用语义版本控制，而不是经典的 Ansible 版本号。这主要与预发行版相关。如果设置为true，则忽略release_tag_re和pre_release_tag_re。
release_tag_re（字符串）¶
默认值为((?:[\d.ab]|rc)+)。
此值用于检测是正式发布版本还是预发行版本。这是一个正则表达式，匹配以v开头的版本字符串。
如果use_semantic_versioning设置为true，则忽略此设置。
pre_release_tag_re（字符串）¶
默认值为(?P<pre_release>\.\d+(?:[ab]|rc)+\d*)$。
此值用于检测是预发行版本。这是一个正则表达式，匹配以v开头的版本字符串。
如果use_semantic_versioning设置为true，则忽略此设置。