跳至内容

其他项目的变更日志

antsibull-changelog 工具允许您创建和更新任意项目的变更日志，类似于 ansible-core 或许多依赖于 antsibull-changelog 的 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 --is-other-project /path/to/your/project

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

  1. `title`：默认为 `Project`。请将其替换为您的项目名称。
  2. `output_formats`：默认为 `[rst]`。将其更改为 `[rst, md]` 以输出 RST 和 MarkDown 版本的变更日志，或更改为 `[md]` 以仅输出 MarkDown 版本。
  3. `use_semantic_versioning`：默认值 `true` 假设版本号遵循 语义版本规范。这主要影响预发布检测和版本排序。
  4. `keep_fragments`：默认值 `false` 在发布完成之后会删除片段文件。如果您希望保留旧版本的片段文件，请将其设置为 `true`。如果您想在发布后删除片段，但将其存档到另一个目录，您可以将 `archive_path_template` 选项与 `keep_fragments: no` 结合使用。请参见下面列表中的其用法。
  5. `changelog_filename_template`：默认值 `../CHANGELOG.rst` 相对于 `changelogs/` 目录。
  6. `always_refresh`：请参阅 "更新/刷新 changelog.yaml" 以了解如何刷新变更日志片段和/或插件说明。
  7. `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 --version <version>

在项目的树中。如果您不想要默认值（今天），也可以使用 `--date 2020-12-31` 指定发布日期。

进行发布时，变更日志生成器将读取变更日志中尚未提及的所有变更日志片段，并将它们包含在 `changelogs/changelog.yaml` 中的新条目中。

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

更新/刷新 changelog.yaml

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

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

  1. `always_refresh` 配置是一个字符串，具有以下值之一

  2. `none`（默认）：等效于未指定 `--refresh-fragments` 和 `--refresh`；

  3. `full`：等效于指定了 `--refresh-fragments with-archives`，或者 `--refresh`；

  4. 逗号分隔的列表，其中支持以下条目

    • `fragments`：等效于指定了 `--refresh-fragments with-archives`；
    • `fragments-without-archives`：等效于指定了 `--refresh-fragments without-archives`。

  5. `--refresh` 命令行参数等效于 `--refresh-fragments with-archives`。

  6. `--refresh-fragments`：如果指定，则所有版本的片段将从变更日志片段文件重新创建。只有在 `keep_fragments` 为 `true` 或存在片段存档（参见 `archive_path_template` 选项）时才有可能。请注意，如果并非所有片段都被存档或保存在片段目录中，它们将从变更日志中**删除**。

  7. `with-archives`（默认）：使用存档和当前片段目录来更新片段。

  8. `without-archives`：仅使用当前片段目录来更新片段。已移动到存档中并且不再存在于片段目录中的片段将从变更日志中消失。

变更日志片段类别

本节描述在默认配置中创建的部分类别。如果您确实需要，可以更改它们。

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

类别的完整列表是

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 都需要一个变更日志片段，这将非常有用。

示例

有关如何编写变更日志片段的指南，请参阅 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 的片段示例如下所示

release_summary: |
  This is the first proper release of ``antsibull-changelog`` on 2020-06-20.