协议

协议是一个变更日志生成器。

协议允许你在单独的文件中维护你的变更日志片段，然后在发布前将它们聚合到CHANGELOG的新部分。

目录

• 背景
• 安装
• 使用
• 维护者
• 贡献
• 许可

背景

变更日志是一个非常好的主意https://keepachangelog.com/。不幸的是，当与版本控制结合使用时，它也有些麻烦。

• 不同的合并请求都会编辑CHANGELOG中的同一区域，不可避免地导致合并冲突。
• 如果主分支的CHANGELOG中尚未存在未发布版本的章节（通常在发布后不久），功能分支必须创建此章节。如果有多个功能分支这样做，你会得到更多的合并冲突。
• 旧的合并请求在合并时，有时会将它们的变更日志条目添加到已发布的发布版本的部分。

如果不需要处理这些问题，生活将会容易得多。

输入Protokolo（Esperanto中为“报告”或“会议记录”）。这个想法非常简单：对于每个变更日志条目，创建一个新的文件。最后，在发布之前，将那些文件的 内容编译成CHANGELOG中的新部分，并删除这些文件。

另请参阅

Towncrier 是相同想法的一个较老且更广泛使用的实现。Protokolo的独特之处在于它使用目录层次结构，而不是将所有元数据放在每个变更日志片段的文件名中。此外，Protokolo不对片段进行复杂的格式化——你写什么就得到什么。

我在Towncrier中遇到了三个主要问题，而Protokolo试图解决这些问题

• 使用Towncrier时，我总是会忘记我有哪些片段类型可用，并需要查找。这些片段类型也可能因仓库而异。在Protokolo中，类型总是可见的，因为它们是目录。
• Towncrier片段按其ID排序，通常是问题或PR编号。这并不总是我想要的。
• 由于（某些）Towncrier工作流程将PR编号作为元数据放入文件名中，我必须在创建变更日志片段之前打开PR。

我年轻一些的时候也尝试编写了一个类似的程序，名为 changelogdir。

安装

Protokolo是一个常规的Python包，托管在 PyPI 上。您可以使用 pipx install protokolo 安装它。确保使用 pipx ensurepath 将 ~/.local/share/bin 添加到您的 $PATH。

使用

有关完整文档和选项，请阅读 https://protokolo.readthedocs.io 中的文档。

初始设置

要将您的项目设置为使用Protokolo，请运行 protokolo init。这将创建一个 CHANGELOG.md 文件（如果尚未存在）以及在 changelog.d 下的目录结构。目录结构使用 Keep a Changelog 部分，最终看起来像这样

.
├── changelog.d
│   ├── added
│   │   └── .protokolo.toml
│   ├── changed
│   │   └── .protokolo.toml
│   ├── deprecated
│   │   └── .protokolo.toml
│   ├── fixed
│   │   └── .protokolo.toml
│   ├── removed
│   │   └── .protokolo.toml
│   ├── security
│   │   └── .protokolo.toml
│   └── .protokolo.toml
├── CHANGELOG.md
└── .protokolo.toml

changelog.d 中的 .protokolo.toml 文件包含其各自部分的元数据：部分标题、标题级别和顺序。它们的包含是强制性的。

项目根目录中的 .protokolo.toml 文件包含Protokolo的配置，以减少您在运行命令时需要输入的文本量。

如果已存在 CHANGELOG.md 文件，请确保在最新发布标题之前添加一行包含 <!-- protokolo-section-tag --> 的内容。

添加片段

要添加变更日志片段，创建 changelog.d/added/my_feature.md 文件，并写入类似的内容

- Added `--my-new-feature` option.

请注意开头的项目符号——Protokolo不会为您添加它们。您写什么就得到什么。

您可以添加更多文件。同一部分（即目录）中的变更日志片段按文件名字母顺序排序。如果您想确保某些变更日志片段首先或最后出现，请使用 000_ 或 zzz_ 前缀文件名。例如，您可以创建 changelog.d/added/000_important_feature.md 以使其首先出现。

编译您的变更日志

您可以使用 protokolo compile 编译您的变更日志。这将从 changelog.d 中获取所有变更日志片段，并将它们放入您的 CHANGELOG.md 中。如果我们现在运行它，将在 <!-- protokolo-section-tag --> 注释之后添加以下部分

## ${version} - 2023-11-08

### Added

- Added important feature.
- Added `--my-new-feature` option.

changelog.d/added/ 中的Markdown文件将被删除。您可以手动将 ${version} 替换为发布版本，或者您可以在编译时传递选项 --format version 1.0.0 给 protokolo compile 以格式化标题。

维护者

• Carmen Bianca BAKKER carmen@carmenbianca.eu

贡献

代码和问题跟踪器托管在 https://codeberg.org/carmenbianca/protokolo。欢迎您提交任何问题。对于拉取请求，欢迎提交错误修复，但对于新功能，可能首先需要在问题中进行讨论。

翻译工作在 https://hosted.weblate.org/projects/protokolo/protokolo/ 使用 Weblate 完成。如果翻译存在问题，请随意在 Codeberg 上提交问题。

许可

所有代码均采用 GPL-3.0-or-later 许可。

所有文档均采用 CC-BY-SA-4.0 OR GPL-3.0-or-later 许可。

一些配置文件采用 CC0-1.0 OR GPL-3.0-or-later 许可。

存储库符合 REUSE 标准。请检查单个文件以了解其具体许可。