我如何维护curl的发布说明

我相信优秀的产品需要清晰全面的文档。我认为发布高质量产品需要提供详细且信息丰富的发布说明。在curl项目中，我努力践行这一理念，以下是我们具体的实现方式。

脚本是您的朋友

我使用一些脚本来维护发布说明及相关文档。

maketgz

让工作顺畅进行的基础脚本是maketgz，这个单一调用脚本能够从当前文件系统内容组装发布压缩包。我们可以在cronjob中运行它，轻松生成每日快照，这些快照看起来就像我们在那个时间点进行正式发布一样。为此我们专门开发了容器化版本dmaketgz，在特定的Docker设置中运行。这个脚本版本能够构建完全可复现的发布压缩包。

如果您想验证发布压缩包的所有内容是否仅源自git仓库和相关的发布工具，我们提供了verify-release脚本来实现此目的。

release-notes.pl

每个发布版本的重要文档当然是RELEASE-NOTES文件，它详细记录了自上一个版本以来所做的所有变更和修复。同时，它也为所有参与并帮助完成此特定版本发布的人员提供了应有的荣誉。

我们为curl使用相当简单的git提交信息标准。它详细规定了第一行应如何构建，以及如何在信息中指定元数据。遵循这种信息格式使我们能够围绕git历史编写脚本并实现自动化。

当我调用release-notes.pl脚本时，它会执行git log命令，列出自上次提交RELEASE-NOTES文件（提交信息为"synced"）以来仓库中的所有变更。然后解析这些变更：第一行用作发布说明条目，信息中的问题跟踪器引用用于链接变更，方便用户追踪其来源。

脚本本身无法实际知道提交是变更、错误修复还是其他内容，因此在调用后，我必须手动检查更新后的发布说明文件。我会检查新添加的条目，删除不相关的条目，并将涉及变更的行移动到变更列表中。

然后我运行release-notes.pl cleanup，这会清理发布说明文件——按字母顺序排序错误修复列表，并删除不再使用的孤立引用（针对在上述过程中删除的先前列出的条目）。

contributors.sh

调用此脚本时，它会提取自最近发布（标签）以来项目的所有贡献者。包括提交作者、提交者以及在所有提交信息中获得荣誉的人员。还包括同一时期web仓库中的所有提交者和作者。它还会考虑现有RELEASE-NOTES文件中提到的现有姓名。

它会清理姓名，通过THANKS-filter运行它们，然后以便利的方式和格式输出每个唯一姓名，方便直接复制粘贴到RELEASE-NOTES中。

delta

delta脚本输出与最近发布版本相比，仓库当前状态的数据和计数器。

在终端中调用脚本会显示类似以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

= Since curl-8_12_1 Feb 13 08:18:33 2025 +0100
=Elapsed time:       10.4 days (total 9837 / 10331)
Commits:            122 (total 34405)
Commit authors:     14, 1 new (total 1343)
Contributors:       19, 8 new (total 3351)
New public functions: 0 (total 96)
New curl_easy_setopt() options: 0 (total 306)
New command line options: 0 (total 267)
Changes logged:      0
Bugfixes logged:     67 (6.44 per day)
Added files:         10 (total 4058)
Deleted files:       2 (delta: 8)
Files changed:       328 (8.08%)
Lines inserted:      7798
Lines deleted:       6318 (delta: 1480)

通过这个输出，我可以更新RELEASE-NOTES文件顶部的计数器。

然后我使用提交信息"RELEASE-NOTES: synced"提交RELEASE-NOTES文件，这样自动化系统就能准确知道它上次更新的时间。

重复操作

在我的~/.gitconfig文件中，我有一个有用的别名：

1
2

[alias]
    latest = log @^{/RELEASE-NOTES:.synced}..

这让我能够轻松列出自上次更新发布说明文件以来仓库中的所有变更。我经常这样列出它们：

1

git latest --oneline

这样会以每提交一行的方式列出所有提交。如果列表足够大，可能有20-30行左右，并且距离上次更新已经过去几天，我可能会更新发布说明。

每当有curl发布时，我也会确保发布说明文档完全更新并适当同步。